
The Journal of Macintosh Technology and Development 




Cisco Srirtiit 


Also in this issue. 


First Steps 

by Aaron Montgomery 

A Postscript IDE via 
a BBEdit Plug-In 

by Larry Taylor 


$8.95 us 
$ 12.95 Canada 
ISSN 1067-8360 
Printed In U.S.A. 


0 32128 74887 8 


04 















































Call for a TeraMedIa* demo 

^TeraGlobal" 

COMWUNJCATiONS 

(858) 404.5500 ext 5660 
www.teragiobal.cofn 
sales@tera 9 J 0 bal.com 

•lu 

n* 

NgitalONA 


Interact Collaborate. It's highest-quality multi-point 
video conferencing and true real-time multimedia 
collaboration. It's all done in software. Any number 
of users. Over any distance. At any time. In real time. 
It flies, you don't 

video lat^icy^varks with IV y| MM A ¥ 11. j\ M M MM. 

In most cases, T€raMerfi3*l3^ T 

the threshold of human perteptioa Qy | 0r3GIOo3l 

























































''Neverforget that the most powerful 
force on earth is love ” 

-Nelson A. Rockefeller ^ 



Move over love. 


Get a new Apple PowerMac™ G4 
or one of our refurbished models 
at price you will L-O-V-E. 



1673 Main Street 
Waitsfield,VT 05673 USA 
Phone; 802 - 496-7171 
Online; smallilog.coiii 



Apple SpedalLst 


©2000 Appie Compuler Inc. M nghts resemed The Apple logo is a rq^stemd trade?mrk ajid IbwerMac is a tradermrk of Apple ConilmieK 












77m? Journal of Macink^b Technology & DetH^loprnent 


A publication of XpLAIMCoRPORATION 


How To Communicate With Us 


In this electronic age, the art of 
communication has become both easier 
and more complicated. Is it any surprise 
lliat we prefer e-mail? 

If you have any questions, Feel Free to call us 
at 805/494-9797 or fax us at 805/494-9798. 

If you would like a subscription or need 
customer service, feel free to contaa 
Developer Depot Customer Service at 
B77~MACn:ai 


OEPAKIMENTS 

E-MaaaJKL 

Orders, Circulation, & Customer Service 

t;usi_service@mactcxh .com 

Press Releases 

prcss_R:lcaLses@ma ctech *uom 

Ad Saks 

ad_s3les@iTiactech.a>m 

Editoriai 

editorial@ma ctech .com 

Programmer’s CliaUeiige 

piTog_clialleng^@mactech .com 

Online Support 

online® inactech .com 

AccoLuilii^ 

aa.xxiniing® mactech.com 

Marketing 

markding^niiictechHCom 

General 

info@mactech .com 

Wtb Site- (artides, inhx URLs and uiO(re,„) 

http;//www.inactech com 


The MacTecb Editorial Staff 
Publisher • Neil Ticktin 
Managing Editor • Jessica Sruhhteiield 
Online Editor • Jeff elites 

Regular ColumnUts 
Cietting Started - Networking 
by John C. Welch 
Programmer’s Challenge 
by Boll Botmsira 
MacTech Online 
by Jeff elites 

From tlie Factory Floor 
by Mclrowerks 

Regular Contributors 

Vicki Brown, Andrew Stone, 

Tim (VIorux>c, Erick Tejkowski, 

Kas Thomas, Will Poner, 

Paul E. Scvinc\ Tom Djajadiningrat, 
and Jordan nea-Mattson 

MavTech's Board of Advisors 

Dave Mark, Jordan Dea-Maitsrm, 

Jim Straus, Jon Wiederspan, 
and Eric Gundruni 


PRIBTCO WITH 

SOYINK 


This publication is 
printed on paper with 
recycled content. 


MacTech's ConMbuting Editors 

• Jim Black 

• Michael Brian Bentley 

• Tantek ^elik, Microsoft Corjioration 

• Marshall Clow 

• I film, C. Daub 

• Tom Djajadiningrai 

• Bill Doerrfeld, Blue weald 

• Andrew S Downs 

• Richard V. Ford, Packeteer 

• Gordor) Garb^ Coball Networks 

• John Hanay, Apple Computer 

• Lcjrca Harms, San Francisco State University 

• llene Hoffman 

• Cliris Kiibourn, Digital Forest 

• Scon Knastec Microsoft 

• Mark Kriegsrmtn, Clearwiiy Technologies 

• Peler N. Lewis, Stairways Sfjriware 

• Bill McGlasstm, Apple Computer 

• Rich Morin 

• Terje Norderhaug, Media*Design-ln-Progress 

• Nathan Nunn, Purity Software 

• John O'Fallon, Maxum Development 

• Alan Oppenheimer, Open Door Networks 

• Avi Rappoport, Search Tools Consulting 

• Ty Shipman, Kagi 

• Cluick Sliotton, BlAP Systems 

• Cal Simone, Main Event Software 

• Steve Sisak, Codevvel] Corporation 

• Dori Smith 

• Andrew' C, .Stone, w^ww;stone,ccjm 

• Michael Swan, Neon Softw'are 

• Chuck Won Rospath, Plaidwt>rks 

• Bill von Hagen 

• Eric Zelenka 


Xftlain Corporation Staff 
Chief Executive Officer * Neil Ticktin 
Pre?iidcm ■ Andrea J, Snider man 
Controller ^ Michael Friedman 
Production Manager • Jessica Stubblefield 
Prciduetion/Layout • W2 Graphics 
Marketing Managers 

Nick DeMcIlo and Alyse VV)iirist 
Events Manager • Susan M. Worley 
Network Administrator • Ikn Baumer 
Accounting ■ [:in Webber, Marcie Moriarty 
Customer KelaLions ■ liiurd Lane 

Susan Pomrantz 

Shipping/Kecelviflg • Jtjel Heardie 

Board of Advisors • Steven Geller, Blake Park, 
and Alan Carsrud 


All cnntentji are t}t)pyrigfit 1984-2[)(ll by Kpkin Q>rpomiion. 
All rights rL'servL'j. MaLTfch and Developer Depot are 
registered tmdcniafks of Xpliiin Ojrporation. RadGad. Useliil 
Gifts and Gadgets. Xpkin, DevDepert. l>ep^3t, The l)ept>t 
DepcH Store, Video DepX, Movie DeptH, Palm lX‘poi, Game 
Oep^)^, Pladilighi Depot, Explain It, MacDev-L THINK 
HeferenLX', Netl'roFexskml, Netl^roLive, JavaTech, WdiTedi, 
BeTech, LinuxTedi, MacTech G^ntml tmd the MacTutorMan 
are trademark^; or Venice marks f>f Xpluin CorfHiratifm. 
Sprocket is a registered trademark d' eSprrxkc-t Qjij^raiion, 
Other trademarks and copyrigltts apfximng in tliLs printing or 
srjftware remain tlie property nf ttieir respective hcildere. 


- :'± . -J -1- J - -. - ■ 4-... ' —---^ --- 

MacTech Magazine (ISSN: 1067-8360 / USPS: 010-227) is publLshcxI mcxithly by Xplain CxjrponUjon, 850-P Hampshire Road, Wesd^e Vftlage, CA 91361- 
2800. Voice; 805/494-9797, EAX; 805/491-9798, Domestic subscription rates are HlW per year, Canadian sulmTiptions am $59.00 pei‘ year. AE other 
international suhscriptioas are $97.00 per year. Domestic source cxxle disk .subscriptioas aie $77 per year All international disk subsoiptidjis are $97.00 a 
year, Please remit to tltS. funds only. Periodical postage is paid at Thousjtnd Oaks, CA and at additional mailing office. 

POSTMASTER: Send address changes to MacTech P.0, Box 5200, Westlake Village, CA 91359-5200, 


2 


The Staff 


MaCTecu • Apkii, 2001 





























C. o n t e n t .s 


April 2001 • Volume 17, Issue 04 


FeafUfe A i tit les 


QuiCKTiME Toolkit 

S An Extremely Goofy Movie 

by Tim Monroe 

ADC Direct 

52 Darwin: Mac OS X's Core 0$ 

Mac 05 X 

58 Help On The Way! 

by Andrew Stone 


Columns 



Mac OS X. ........ Page 58 


Viewpoint 

4 Mac OS X Briefing 

by Rich Mofin 

Programmeh’s 
Challenge 
56 Crossword II 

by Bob Boonstfo 

92 MacTech Online 

by Jeff elites 


Cover Story 

80 Multihoming Your 
Network Using the 
Border Gateway 
Protocol (BGP) 

By Chris Kilbourn 
Edited by Justin 1/1/. Newton 


Programming Techniques 

3J A Postscript IDE via a BBEdit 
Plug-In 

by Larry Taylor 

PowerPlant Workshop 

43 First Steps 

by Aaron Montgomery 


QuickTime Toolkit 


.Page 8 



ApmL 2001 • Mac^f.ch 


Table of Contents 


3 









































































VIEWPOniT 


by Rich Morin 


In this month's Viewpoint, Rich Morin revisits mme themes tliat 
he disQLssed in our first Viewpoint, two years ago. Fortunately, 
Apple has now^ released Mac OS X, so much of what used to lie 
speculation Is now reality. 

I am an unapoiogetic fan of lioth Mac OS and Unix. My desktop 
system (cerl>^rus) is a three-headed 03, running Mac OS. A FreeBSD 
server sits downstairs, providing support for email, ftp, telnet, etc. 
The Mac provides a pleasant user interface and a fine set of 
“productivity tools”; the server gives me a reliable platform for my 
Unix-lxLsed programming projeas. 

Alfoough I find tliis to be a very workable combination, it can 
prove awkward on cjceasion. The FreeBSD and Mae OS 
environments are not tiglilly coupled, so moving infonmrion 
lx.*tween iliem can be a nuisance. Al^stj, Mae OS apps liave a 
tendency to use und(x.iimented, propriemiy^ file formaLs. Tlie idea of 
an integrated system, based on lioth Mac OS and Unix, Is themfbie 
t[uite appealing to me. 

More to the point, 1 once had such a sy.stem. A/ljX, which ran 
on the Mac II and follow-on machines (e.g., Quadius), was a very 
promising blend of Mac OS and fTnix. llnforUinately, Apple never 
gjive tlie product any real marketing support, so it never built a large 
customer base. Nonetlieless, it wiis a useful and interesting “pitxjf of 
concept”, solving some hard problems in an elegant tashion and 
offering .stime real innovations. 

A dec’ade later, hard warn advances have given us Macs tliai are 
a diousand times faster tlian a Mac Ik disk drives tliat are a tliousimd 
lijiies larger, etc. Tliis computing power ha,s allowed a numlK'r of 
“hideously inefficient” stiftware innovations (e.g., Interface Builder, 
Java, OpenGL, XML) to bectane practical. Bringing aO of tliis 
together, Apple is .set to try again, in a mucli more splendid fashion. 
Apple’s engineers have managed to eomliine great engineering willi 
a very stylish and apiiealing appearanc'e. I lliink they are piLsed to 
shake up tlie industry. 

Nonetheless, Apple faces some real problems in pre.senting 
this mixture to the world. They warn it to l>e accepted as “the next 
genenition of Mac OS” by their users and developers, [f they aikiw 
the Unix infrastnicmre to slitjw through, they may scare away 
their tmditional user base. Fven talking up the Unixish lienefits of 
the product (e.g., stability, performance, industry' standard 
ititerfaces) may work againsi tlie aim of easy acceptance by tlieir 
current users and developers. 

On tlie other liand, these same LInixish aspects are critical to 
liringing in useis ^md developers from Linux, Solaris, etc. Two years 
ago, 1 dared to predict that **Apple will cater to, and actively wex) 
academic, research, and otheiwdse teclinical users; in short, the 
bastions of die Unix community. Apple may be quiet abc>ul it, but 
mark my words; it wall be a latge pari of their planning.'' Apple has, 


in tact, Ix^n so quiet alxiut Unix drat it mlglit as w'ell liave 
disappeared from dieir plaas, entirely. They also made some 
discx>uraging decisions, such as killing off any passibility of case- 
sensitivity from HFS+. 

On the other hand, a few' ptisltive indications have also 
surfaced. For one thing, Apple opted to keep UFS around, 
prfwiding case-sensitive file names for situations that really need 
them. Then, at W^'DC, Steve Jobs said that Mac OS X used a 
“Linux-like'' kernel. At MacWorld, Apple actually used the “U- 
word” on tlie large banner that sat atop their pavilion. Finally, 
and most usefully, Apple made its developer tools available to 
Mac OS X Beta users, without demanding a stiff entry fee that 
might have discoumged casual developers. 

None of foese indications prepared me, however, for Apple’s 
recent moves. Making the Unix command line (and a full suite of 
comnrmds) available to all users is really a liold move for a company 
tliat preaches (and pracLices) extreme sunplicity in user interfaces. 
Shipping a developer UD-H(3M in llie Mac OS X distribution is even 
more radical; what do tliey think tlie typical Mac OS user is going to 
do with Interface Builder? 

Well, Joe and Sally Sikspak may not want to load the 
develtJper disc, luii iheir son or daughter may. The BSD 
command set found in Mac OS X is almost indistinguishable from 
that of the Linux machines the kids have teen using, so they’ll 
find the basic tool ser c|uite comfortable. In addition, however, 
they will be able to try out Interface Builder (a real step up from 
hand-coding XI1 calls), Project Builder, and Apple's other 
innovations. In shoii, kids who have been hacking on Linux 
systems for years sliould find Mac OS X to be a real treat! 

If Joe or Sally hapjxns to an engineer, die kids may have 
some Lt)mpetition for time on tlte machine. But dicn. Power Macs 
are cheap enough diat each iiiemlx.T of the family may have one, 
Tltey arc also cheap enough tliat Jcx: or Sally my decide to replace 
die Sun or SGI box on dieir desk witli a G4 cube. Apple may claim 
that it isn’t in the wTirkstation business, diat diat won't keep people 
from buying Macs and using them as workstations! 

In any case, it appeals that Apple is finally ready to 
acknowledge the value that the Unix user and development 
comiTiunity Cfoniial and infomiitl) has to t>ffer. By making powerful 
development tcxils available to all users, they hope to entice all .sorts 
of Unix aficionados to consider Mac OS X as a real platform. If they 
succeed in their effort, die results will bring some real changes to die 
Mac OS developer community. 

Traditionally, Macintosh developers have constituted a 
vanishingly small percentage of the overall community. Let's 
say that there are 24 million Apple users. MacTech, the 
technical publication for devek)pers, has a circulation of 
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something like 20,000 — less than of the entire user 
community. These are generally the more serious developers 
in the community. Even if we expand the definition of 
Mevelopef" to be as broad as possible, w^e only get a total of 
150,000 developers (still less than 1% of the Mac community). 

Now, let's look at die Unix community {including Linux, 
*BSD, Solaris, etc). I don't know the total size of diis communit>^ 
(nobody does, actually but it's clearly in die millions and 
quite possibly in die tens of millions. Now, how many of these 
folks are "developers'? Well, diat’s a hard question, because the 
definition is a lot fuzzier than is is in the Mac community. 

I w’^ould guess that at least half of the Unix community 
(i.e., user.s, system administrators, programmers) have 
wTitten .some shell or Perl scripts. I w'ould nt>l be surprised 
to learn that the majority tif Unix users have written and 
compiled a few^ C programs. Just using the command line, 
wliich essentially all Unix users do, is in fact closer to 
programming than most Mac users ever come. In short, it’s a 
ver>" different user community. 

Capturing a million or so of these users for the Mac 
could be a real coup for Apple, Hie raw' numbers aren't that 
impressive; a million additional users would only add abcRit 
4% to Apple's user base. Most of these folks would qualify, 
however, as potential Mac OS X developers. They might be 
.scientists, engineers, studenls. or hobbyists, but many of 
them are in a position to create new' s{)ftware (and retrofit 


old software) for die platform. 

Although existing Mac OS developers could view this as 
unwanted conipetition, I think this would be misguided. 
Instead, I hope that the current band of developers will 
recognize the newcomers as a source of cross-fertilization 
and useful lore. Unix is, after all an enormous, decades-old, 
distributed laboratory' For computer science research. It 
would be very .surprising if the old-line Unix hackers didn't 
have some interesting tricks to show the Mac OS developers. 

Also, the Mac community' has lieen largely unallcctcd by the 
Tree Software” and "Open Source” movements. Freeware, in 
Mac parlance, is proprietary^ binary-only software which is 
distributed at no charge. Hiis kind of distribution is almost 
unknown in Unix circles, wliere "free softw^are” always allow^s 
iiispecdon, modification, and redistribution of the source code. 
An influx of Unix-style free softw’are might well change the 
thinking of many Mac OS users and developers. 

By the same ttiken, Mac OS developers have a great deal to 
shc)W' (and tell) the newhies. Mac OS X may change some things 
about the UT, but a lot of the principles of Mac interface design 
will carry right through into tlie nevv system. More to the point, 
if w'e want Aqua to avoid the anarchic slate of XI1 applications, 
some advice and counsel will lie quite necessary! 

In short, it's a win-win situation. We all get to play W'itli some 
really nifty development tools, on .some really terrific liardware. We 
also get to tiy ()Ui thousands (literally!) of Open Source programs, 
either under their original command-line and/or XU user 
interfaces or with nevv, A{L|ua-based liont ends, ffij 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


An Extremely Goofy Movie 


Using Video Overrides and Tweening 
in Sprite Movies 

Introduction 

In the previous QuickTime Toolkit anicle (*‘A Goofy 
Movie" in MacTech, March 2001), we learned how to 
create some simple sprite movies. We saw that a sprite 
track typically contains two kinds of media samples, key 
frame samples and override samples. A key frame sample 
contains the set of images used by all the sprites in the 
track (up to the next key frame sample) and information 
about the initial properties of those sprites. An override 
sample contains only information about changes in the 
properties of the sprites. It’s these changes that allow us 
to perform sprite animation with override .samples. 

In this article, we're going to investigate two ways to 
perform sprite animation without using override samples. 
We’ll see how to use a video track as tJie source for a 
sprite's images, and well see how^ to interpolate a 
sequence of values for a sprite property. Given a starting 
value and an ending value, QuickTime is able to figure 
out, for any moment in the duration of the animation, 
what the appropriate value between those two values 
should be. This process is called tweening, and the track 
that contains the information needed to do the tweening 
is called a tween track. 

Video override tracks and tween tracks are two kind.s 
of modifier tracks, or tracks whose media data is used to 
mr)dify data in some other track. Modifier tracks do not 
display their data directly in a movie. Rather, that data is 
used only to supplement or alter the data in some other 
track in the movie. A video override track supplements 
the data in a sprite track by providing a source of images 
for one or more sprites in that track. And a tween track 
can modify the data in a sprite track by providing a 


sequence of settings for one of the properties of a sprite 
in that track. For example, we can use a tween track to 
generate a sequence of horizontal positions for a sprite. 

We’ll begin by seeing how to use a video track as a 
source of image data for a sprite. Then well turn our 
attention to tweening. Tweening is an extremely useful 
technique throughout QuickTime, not just in connection 
with sprite properties. So it will he good to spend some 
time getting comfortable building tween tracks. 

Our sample application this month builds on last 
month’s QTSprites application, so Fve called it 
QTSpritesPlus. Figure 1 show.s the Test menu of 
QTSpritesPlus. 


Test 


Hake llideo Sprite Mouie... 981 

Hake Houing Icon Hooie... 982 
Hake Spinning Icon Houie... 983 
Hake Rolling Icon Moifie... 984 

Hake Penguin Home..,965 


Figure 1: The Test menu of QTSpritesPlus 

These menu items build mr>vie.s that are modifications of the 
icon and penguin sprite movies that we built last time. The 
first menu item builds a movie that contains two sprites, and 
the image of one of those sprites is overridden by the frames 
from a video track. The next three menu items use tween 
tracks to perform different spatial animations on the icon 
sprite (moving it to the right, spinning it in place, and then 
botli moving and spinning it at the same time). The last 
menu item !>uilds die appearing-penguin movie once again, 
this time using a tween track to change the graphics mode 
of the penguin sprite image. 


Tim Monroe is a member of the QuickTime engineering team. You can contact him at monnx^@apple.com. 
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Video Override Tracks 

It'5 actually quite simple to use a video track as the 
source for a sprite's images. We need to add a video track 
to our sprite movie, create a track reference from the 
sprite track to the video track, and then indicate to the 
sprite track how it is to interpret the data that it receives 
from the video track. Figure 2 shows our video override 
movie. Here, the sprite track contains two sprites; the 
image of one of those sprites is a picture of the Titanium 
FowerBook G4, and the image of the other sprite has 
been replaced by the frames of the video track. By 
properly setting the positions of both sprites and choosing 
a video track with just the right dimeasions, we can get 
that video track to exactly overlay the screen of the 
PowerBook. 



Figure 2: A sprite image overridden by n video track 


Building a Sprite Track 

The first thing need to do, tjf course, i.s build a 
new movie that contains a sprite track. In the present 
case, as just mentioned^ we'll build a sprite track with a 
single key frame sample, wliich contains two sprites and 
two sprite images. What's different from the previous 
article is that we wx>n1 add any override frames to the 
sprite track. (In fact, if w^e were to add some override 
samples that change the sprite image index, we'd likely 
get some very strange results wlien we ran the movie, in 
technical terms, the results are undefined; in layman’s 
terms, don't do it!) We'll set the duration of the key frame 
sample to 30 seconds (which is the duration of the video 
track we want to use as our image trverride track). Listing 
1 shows the definition of the function 
QTS p rites_Atld 1 ^owerBookMovieSamplesToMedia, which 
we use to add the sample to the sprite track. 
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Listing 1: Adding a single key frame sample to a sprite track 


QTSpritt'ji, AddPuwcr[i(xikMovkSumplc^ToMedia 


void QTSprites„AddPo-werBaokMovlGSainplesToMedia 
(Media theHedia) 


[ 


QTAtomContainer 

QTAtomContainer 

RGBCalor 

Point 

short 

OSErr 


mySample = NULL; 
mySpriteData ^ NULL: 
myKeyColor; 
myLocation: 

IsVisible, myindex. myLayer: 
myErr = noErr: 


// create a new, empty key frame sample 

myE r r = QTNewAt omCont ain er (SmySa ra p1e ) : 

If (myErr 1= noErr) 
goto bail: 

myKeyColor.red = rayXeyColor,green = myKeyColor.blue ^ 
Oxffff; //while 


// add images to the key frame sample 

S p rit eUti1s_Ad dPICTIma geToKeyF r ame S ample {my Samp1e. 

kOldQTIconrD. ^myKeyColot, 1, NULL, NULL); 
SpriteUtils_AddPICTImageToKeyFratiieSample [my Sample. 

kTitaniumPowerBooklU* SmyKeyColor; 2, NULL. NULL); 

// add the initial sprite properties to the key frame sample 
myErr = QTNevAtomContainertiimySpriteData] ; 
if (myErr !“ noErr) 
goto bail: 

// die QT Icon sprite 

myLocation,h = 46; 

myLocation,V = 8: 

isVisible “ true; 

mylndex “ kOldQTIconlitLageladex: 

myLayer = 1: 

SpriteUtils_SetSpriteOata (mySpriteBata. ^intyLocation. 

SisVlsiblE. SmyLayer, SmyIndex. NULL. NULL. 

NULL): 

SpriteUtils_AddSpriteToSample(mySample. mySpriteData. 
kQTIconSpriteAtomlD): 

// the Pow^erBook sprite 

myLocation.h = 0; 

myLocation.y ~ 0; 

isVisible = true: 

mylndex = kPowerBooklmagelndex; 

myLayer ™ 2 : 

SpriteUtils_SetSpriteData(mySpriteData, imyLocation, 

&isVisible, SemyLayer, Index, NULL, MILL, NULL); 
SpriteUtila^AddSpriteToSamplG (my Sample, mySprlteUata. 
kTitaniumPowerBooklD): 

SprltGUtilE_AddSpriteSa!iipIeToMedia (tbeMedia. mySample , 

kSpriteMediaFranLeDurationPowerBook, true. NULL): 


hail: 

if (mySample t“ NULL) 

QTDisposGAtomContainer(mySample): 

if [mySprlteUata 1= NULL) 

QTDisposeAtomContainer(mySprlteUata): 

1 


See last month's article for details on die sprite utilities 
(such as SpriteUtils_SetSpriteData) used in Listing L 


Adding a Video Track 

Now let's add a video track to the sprite movie. We'll 
do this by copying an existing video track from another 
movie into the sprite movie. We want the video track to 


be at least as long as the sprite track, so that there are 
enough frames to replace the sprite image for the entire 
duration of the sprite track. For simplicity, we'll make the 
video track exactly as long as the sprite track. Figure 3 
shows the track layout that we want to achieve. 


spiitBirad« 


VideoJraik 


Figure J; 77je stmeture of the video override movie 

There are actually quite a number of ways to use 
QuickTime APIs to copy a video track from one movie to 
another. We could, for instance, iterate through the 
samples in the source video track and call 
AddMediaSample to copy them one by one into a new 
track in the sprite movie. Or w^e could select tlie entire 
source movie and then call the AddMovieSelection 
function to insert the selection into the sprite movie. Or 
w^e could u.se the InsertTrackSegment funciion to insert 
the entire source track into the sprite movie, ThaTs the 
strategy we’ll use in the QTSprites^lmportVideoTrack 
function, shown in Listing 2, 



Listing 2: Copying a video track from one movie to another 


QTSpriics^ImportVtdcoTrack 


OSErr QTSprltes_ImportVideoTrack 

(Movie theSrcMovie, Movie theDetMovie, Track *tbeTrack) 


Track 

raySrcTrack = NULL 

Media 

mySrcMedia = NULL 

Track 

myDstTrack = NULL 

Media 

myllist Media = NULL 

Fixed 

myWidth* myHeight 

OSErr 

myErr - paramErr; 


// get the first video track in the source movie 

mySrcTrack = GetMovieIndTrackType(theSrcHovie, 1, 

VldeoMediaType, movieTrackMediaType); 
if (mySrcTrack “ NOLL) 
goto bail: 

// j^et die track’s media and dimensions 
mySrcMedia = GetTrackMedia[mySrcTrack): 
GetTrackDijitenalcjnsfinyStcTrack, ^irsyWidth, ^inyHelght): 

// create a destination track 

myUetTrack = NewMovieTrackitLeUEtMovie, myWldth, myHeight, 
kNoVolume}; 

if (myUstTrack = NULL) 
goto bail: 
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// create a destiaation medb 

myDstMedia “ KewTrackMedia(myDstTrack* VideoMediaType* 
GetHediaTlmeScaletmySrcMedla}, 0* 0): 
if (myDstMedia ^ NULL} 
goto bail; 

ittyErr = BeginMedlaEdlts (myDstMedia): 
if (myErr t= noErrJ 
goto baili 

myEtr = GopyTrackSettingsCmySrcTrack* myDstTrack)j 
if (myErr 1= noErr) 
goto bail: 

myErr = rnsertTrackSegment{mySrcTrack* inyDstTrack^ 0. 

GetrrackDuratlon(mySrcTtack), 0): 
if (myErr != noErr) 
goto bail: 

myErr = EndMediaEdlts(myDstMedia): 
if (myErr != noErr) 
goto bail; 

bail: 

if (theTrack t= NULL) 

*theTrack " inyDstTrack: 

return(myErr): 

! 


Notice that we call BeginMediaEdits and 
EndMediaEdlts, so that the video track media samples are 
copied into the sprite movie. If we didn't call these two 
functions, the video track in the sprite movie would 
reference the samples in the source movie. (There’s 
nothing intrinsicafly wrong with that, but we generally 
prefer to create self-contained movies.) Notice also that 


QTSprites_lmportVideoTrack returns the new' track that it 
creates to the caller. 

If our call to QTSprites_ImportVideoTrack returns 
successfully, we want to truncate the new video track so 
that it is exactly as long as the sprite track. We accomplish 
this by deleting any portion of the new video track that 
extends beyond the end of the sprite track, like this: 

myDuration GetMovieDuration(theSpriteMQvie); 

myErr ^ QTSpritGS_ImpottVideoTrack(myVideoHovle. 

theSpriteMovie* &myVldeoTrack): 

if (myErr 1” noErr) 
goto bail; 

DeleteMovieSegment(theSpriteMovie, myDuration, 

GetMovieDurationCtheSpriteMovie) - myDuration): 


Adding a Track Reference 

Now we need to establish a link between the video 
track and the sprite track to w'hich it’s going to send its 
data. We do this by creating a track reference from the 
sprite track to the video track. We first encountered track 
references in an earlier article (‘‘Word Is Out'', in 
MacTech, November 2000) when we learned how to 
create chapter tracks. In the present case, we want to add 
a track reference of type kTrackModifierReference from 
the sprite track to the new video track, like this: 

myErr = AddTrackJleference(theSpriteTrack* myVideoTrack, 

kTrackModifierReference, imyReflndex): 
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when QuickTime sees that the video track is the target of 
a reference of type kTrackModifierReference, it knows 
that the video track is a modifier track and hence not to 
draw the video track in the movie box. Instead, it sends 
the video data to the track that contains the reference to 
the video track. 


Setting the Input Map 

But how does the sprite track know what to do with 
the data being sent to it from the video track? In 
particular, how does it know which sprite image is to be 
replaced by those video frames? This information is 
contained in a data structure called an input map that is 
attached to the track's media. A media’s input map 
specifies how the track is to interpret any data being sent 
to it from a modifier track. In other words, whenever a 
movie contains a modifier track, then some other track 
needs to have an input map that tells the associated 
media handler what to do with the data from the modifier 
track. The track reference and the input map work 
together to link a modifier track to its target track and to 
specify hcjw the data from the modific'r track should 
modify the target track. 

An input map is an atom container that contains one 
atom of type kTrackModifierlnpul for each modifier track 
that is sending data to the target track. It's perfectly 
possible that several modifier tracks each send their data 
to a particular target track. In that case, the target track's 
input map would contain several kTrackModifierlnput 
atoms. The ID of each sucli atom must he set to the 
reference index returned by AddTrackReference wlien the 
track reference was created. 

Each atom of type kTrackModifierlnput in an input 
map must contain at least two child atoms. One of these 
children is always of type kTrackModifierType and 
specifies the kind of data the target track is going to 
receive from the modifier track; in the case of a video 
override track, the type of the modifier track input is 
kTrackModifierTypelmage. The file Movies.h defines 
constants for a large number of modifier input types, 
several of w^hich we’ll encounter later in this article: 


enum [ 

kTrackKodlflerTypeMatrix 

kT ra c kModifie rTypeC1ip 

kTrackModif1erTypeGraphicsH d rfe 

kTrackHodifie rTyp eVo1uma 

kTrackModifierTypeBalance 

kTrackModifierTypeImage 

kT r ackMo difierObjec tMa t rix 

kTtackModlflerObjectGraphicsMode 

kTrackHodifierType3d4x4Matrix 

kTrackModlfierCameraData 

kTrackModifierSoutidLocalizatloiiData 

kT ra c kMo d1fie r Ob j ec tIma g eInde x 

kT r a ckNo d 1 f i e i: Ob j ec tLay e r 

kTrackMqdiflerObjectViaible 

kTrackModlfierAngleAspectCamera 

kTrackModifierPanAngie 

kTrackModiflerTiltAngle 


= 1, 

= 2 . 

- S, 

= 3, 

= 4 H 

FOUR_CMR_.CODE{ Wide ’). 
“ 6 . 

= 7. 

- 0. 

- 9 , 

= 10 , 

- lb 
= 12 , 

“ 13, 

= 14 . 

FOUR_CHAK_CODE(^pan *). 
F0UR_Ca4R_C0DE('tilt‘, 


kTrackModifierVerticalFieldOfViewAngle 

- FOUR_CHAR_CODE(‘fov 

kTrackModifierObjectQTEventSend = FOUILCHM_CODE (‘ evnt *} 


The type of the second child atom in an inf)ut map 
entry atom depends on the kind of data specified in the 
first child atom. For instance, with a video override track, 
it specifies the index of the sprite image that is to be 
replaced by the frames of the video track. Figure 4 shows 
the structure of the input map we’li use to attach a video 
override track to a sprite track. 



Figure 4: Ihe sfnicture of an inptii map far video omrrides 

Keep in mind that the sprite images in a key frame 
sample arc stored in a list tiiat is used liy all the sprites in 
that track. This means that tw(3 or more sprites can have 
the .same image (by having their image index property set 
to the same value). So it’s possible that two or more 
sprites can have their image replaced by the frames of a 
single video track. Similarly, it's possible for a single 
sprite to get its image data from first one and then another 
video track. In that case, there would have to be several 
override video modifier tracks and .several 
kTrackModifierlnput atoms in the sprite track's input map. 

Listing 3 shows the definition of the 
QT8prites_AdLlVidcoEntryTolnputMap f li nctitm, which we 
u.se to add the a[3propriate children to an exi.sdng input map. 


Listing 3: Adding a video override entry to an input map 


QTSprites_A(krvidco EntryTolnpuiMap 

GBErr QTSprites_^ddVideoEntryToInputMap 

(QTAtomCqntalner thelnputKap. long theRefIndex, 
long tbelD, OSType theType* char WheName) 


i 
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#p ragitia imus ed {theName) 

QTAt OEn rayInputAt om j 

OEErr myErr = noErr; 

// mUJ an entry to tlie input map 

[iiyErr = QTIneertChild (theInputMap. kParentAtonilaContainer, 
kTrackHodlfierlnpnt* theReflndex, 0* 0, MILL. 

&my Input Atom); 

If (myErr [= noErr) 
goto bail; 

// add two diBd atoms to the parent atom; 

// these atoms dcGne the type of the modiOer input and the imagie index to override 

theType ^ Etidiantf32_Ntofl(tbeType); 

myErr = QTlnsertChildCthelnputMap* rittylnputAtom. 

kTrackKodlfierType, 0, sLzeof (OEType). 
&tbeType, NULL): 
if CmyEri: != noErt) 
goto bail; 

thelD = EndianS32_NtDB(tbeID); 

myErr = QTInsertChild(tbelnputMap» myInputAtora* 

kSpritePtopertylmageIndex, 1. D, sizeof(long) , 
ithelD. HULL): 


bail; 

return(myErr); 


In QTSpritesFlus, we create an input map by calling 
QTNewAtoinContainer: 

myErr = QTNewAtoinContalnerC&mylnpotMap) : 

We create a new atom ct^ntainer because we created the 
sprite track and therefore know that it doesn't have an 
input map yet Alternatively, we can retrieve a media's 
existing input map by calling GetMeduilnputMap, like so; 

myErr = GetMediaInputMap(GetTrackNedJ.a(theSpriteTrack), 

£imy Input Map ) ; 


(In fact, it's probably preferable to call GetMediaInputMap 
always, since it will create a new input map for us if the 
specified media doesn't have one yei.) 

Next we need to call our function 
QTSprites_AddVideoEntryToInpLitMap to add the 
appropriate entries to the input map: 

myErr = Q,TSprites_AddVldeoEntryToInputMap (myInputMap , 
myRefIndex, kOldQTIconimageIndex» 
kTrackModif ierTypeltnage. NULL); 


Finally, we attach the newly-configured input map to 
the sprite track media by calling SetMedialnputMap; 

myErr = 

SetMedialnputMap(GetTrackMedia(theSpriteTrack), 
myInputMap); 


At this point, we can dispose of the atom container that 
we created (or that GetMediaInputMap created for us): 

QTDisposeAtomContainer(mylnpuxMap); 
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Our complete function for adding a video override 
track to an existing sprite movie is shown in Listing 4. 

LLsting 4; Adding a video override track to a sprite movie 


if (njyErr 1= noErr) 

^oto ball: 

uiyErr ^ OpenMovieFaleifiiUiyFSSpec, fiiHiyRefNuin, f sRdPerm); 
if (myEr:r: [= noErr) 
goto bail: 


Ql^prites_Add VideoOverrideTrack 


OSErr 

[ 


QTSprites_AddVideoOverrideTrack 

(Movis theSptiteMovle, Track theSpriteTrack) 


Movie 

Track 

abort 

short 

FSSpec 

OSType 

short 

QTF rameFi1eFiIt e rUPP 
TimeValue 


long 

QTAtomContainer 

OSErr 


njyVldeoMovie ^ NULL; 
myVideoTrack = NULL: 
tnyRefNuDi === kltivalidFlloRofNiim: 
inyResID ^ 0; 
niyFSSpec: 

inyTypeList [] ^ [kQTFileTypeMovie): 

myNumlypes = 2 \ 

myFileFilterUPP = NULL: 

my Duration; 

myRefltidex; 

mylnputHap = NULL; 

myErr “ noErr: 


Hf TARGET_0SJ1AC 

myNuinTypes = 0; 
#endif 


// ha\'u il>c user sckxt a file; make sum it has a video track in it 
retry; 

rnyFilsFiltGrUPP = QTFrame_GetFilGFiltGrUPP 

[[ProcPtr}aTFrame_FilterFlles); 


myErr = QTFrame_GetOneFileWithPreviewtinyNui]iTypes, 

((jrFrameTypeLiatPtr) myTypeList, 
fiimyFSSpec, myFileFilterUPP}; 
if (rayFileFilterUPP E= NULL) 

DisposeNavObjectFilterUPP[myFileFilterUPP); 
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// now fetch the linst movie from ilie Die 
inyResID = 0: 

myErr = NewMovieFroinFlleC&myVideoMovie, myRefNiim, {onyReslD, 
NULL, newMovieActive. NULL): 
if (myErr != noErr) 
goto bail; 

myVideoTrack = GetMovieIndTrackType[inyVideoHovie, 1, 
VldeoMedlaType * niovieTrackNediaType}; 
if (myVideoTrack NULL) 
goto retry: 

// copy the vidw) track into tlx; sprite movie 
myDuratlon = GetMovieDurationltheSpriteMovie); 

myErr ^ QTSprites_ImportVideoTrack(myVideoMovie, 
theSpriteHovie, &myVideoTraek): 
if (myErr I” noErr) 
goto bail: 

// truncate the new video track to the length of tlie sprite movie 
DeleteHovieSegment[theSpriteMovie, tnyUuration, 

GGtMovieI)uration{theSpriteMovie) - my Duration); 

// auacli the video track as a iiaxlLTier to tJie sprite track 

// create a medk input map 
myErr = QTNewAtomContainerC&mylnputHap); 
if (myErr noErr} 
goto hall: 

myErr = AddTrackReference(thoSpriteTrack. myVideoTrack. 

kTrackModifierReference, inniyRefIndex); 
if (myErr [- noErr) 
goto ball; 

myErr ” QTSpritea^AddVideoEntryToInputMaplmylnptitMap. 

myRefInd ex, kOIdQTIc onIma geInd ex, 
kTrackModIfierTypeImage, NULL); 
if (myErr I" noErr) 
goto bail; 

// athicb the input map to die sprite track 

myErr * SetMedialnputMap(GGtTrackMedia(thGSprlteTrack)* 
rayInputMap); 


bail: 

if (myVideoMovie 1= NULL) 
DispOrseMovie(myVideoMovie); 

if (myRefNum !“ klnvalidFileRefNmn) 
CloseMovieFileimyRefNum): 

if (mylnputMap NULL) 

QTDls po seAt omCont ain e r(my1npu tMa p); 

returnCmyErr): 

I 


So it really is fairly siniightforward to use a video 
track as tJie source of a sprite'.s images. IVs mostly just a 
matter of linking the video track and tlie sprite track in 
the correct manner, using a track reierence and an input 
map. As we'll see shortly, we need to perform this same 
linkage between a sprite track and a tween track that's 
sending it data. 
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Tweening 

Tweening is the process of generating values that lie 
between two given values (an initial value and a final 
value) or that are in some other way algorithmically 
derived from some given data. When it w'as first 
introduced (in QuickTime version 2.5), the tween media 
handler .supported only linear interpolation between 
initial and final values. That is to say, if (for instance) the 
initial and final values are integers, then the tweened 
values all lie on a straight line drawn between those two 
values, as illustrated in Figure 5, If the value at time 0 is, 
say, 10 and the value at time 30 is 30, then the tweened 
value at time 15 will be 20. 



Figure 5-' DemAng a value from tnilial and final values 

'fhe tw^een media handler isn’t limited to tweening 
only integer values, however In QuickTime versi(jn 2.5, 
the tween media handler could work w ith a large number 
of types of data, defined by these constants: 

enuin I 

kTweenTypeShort = 1 * 

kTweenTYpeLong 2 , 

kTweenXypeFixed " 3, 

kTwEsnTypePolrit = 4, 

kTwEenTypeQDRect ^ 5, 

kTweenTypeQDRegion " &. 

kTweenTypeMatrix = 7, 

kTweenTypeRGBColor = B, 

kTweenTypeGraphicsModeWithRGBGcilor ” 9, 

kTweenType3dScale = 

kTwee nTyp e 3 dTranslate = ‘31 ra' 

kTweenTypeSdRotate = '3rot' 

kTweenType3dRotateAboutPoint " 'Irap* 

kTweenTypeSdRotateAboutAxla = ‘3rax' 

kTweanTyp e 3 dQua t e rnion = ‘3 qua' 

kTweenTyp e 3 dMat r lx = ' 3tnat ’ 

kTweenType3dCaineraData = '3ca]ii‘ 

RTweenTypeldSoundLocalizationData = *3sic' 

): 


For instance, given two staictures of type RGRColor, the 
tween media handler can generate a third RGBColor 
structure by interpolating the individual fields of the initial 
and final structures. In all the cases listed above, linear 
interpolation is used, although not all fields of a stmcture are 
always interpolated, as wee’ll see later. (We shall ignore the 
3D tween types, as they are used to tween 3D tracks, which 
are not currently supported in Mac OS X.) 


QuickTime 3 0 added support for another few 
handfuls of data types, defined by these constants: 


enum I 

kTweenTypeQTF1 0 atSingle 
kTweenTyp eQTF1o atDouble 
kTweenTyp eFixed P 0int 


- 10, 
= lb 
= 12 , 


kTweenTyp&PathToKatrlxTranslation = F0UR_CHAR_CODE ( 
kTweeniypePathToMatrixRotation = F0UR_CHAR_C0DE( 
RTweanTypePathToMat rixTrans1atlonAndRo t atiort 

- FOUIGCHAIGCODEC 

kTweenTypePathToFixedPoint = F0UR_CHAR_CODE( 
kTweenTypePathXtoY = F0UR_CHAR_CODH( 
kTweenTypePathYtaX - F0UR_CHAR_C0DE( 
kTweetiTypeAtoinList ^ F0UR_CHAR_C0DE C 
kTweenTypePolygon = F0UR_CHAR_C0DH( 
kTweenTypeMultiMatrix =■ F0UR_CHAR_C0DE( 
kTweenTypeSpin = FOOR^CHAIGCODE( 
kTweenTy p 0 3 dMat r ixNonLi nea r = F0UR_CHAR_C0DE ( 
kTweenTypaSdVRObJect = FOUR_CHM_C0DE ( 


'gxmf). 

gxpr’), 

'gxmr'). 
'gxfp■}. 

'gxyx'). 
'atom'), 
'poly'). 
'taulra'}, 
'spin'}H 

'3nlrb P 
' 3vro') 


These new^ tween types provide support for more 
complex tweening operations and for operations that are 
not simple linear interpolations of data. For instance, the 
various type.s of path tweens alkw us to derive values 
based on the shape of an arbitrary curve defined by a 
vector path. And the list tw^een derives values from a list 
of atoms in an atom container, which can result in a series 
of discrete steps of non-continuous values. 
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In the remainder of this article, well investigate four 
of these tween types in detail: 
k T w e e n T y p e G r a p h i c s M o d e W [ t h R G B C o 1 o r, 
kTweenTypeMatrix, kTweeiiTypeSpin, and 

kTweenTypeMultiMatrix. Perhaps well return to consider 
some of the others in a future article. 


Adding a Tween Track 

We add a tween track to our sprite movie in the 
standard way, by calling NewMovieTrack and 
N e wTr a ck M ed i a; 

inyTweenTrack = NewMovieTrack (theMovie. 0. 0. kNoVolinne); 
myTweeiiMedia = NewTrackMedia(inyTweenTrack, TweenMediaType, 

GetMcivieTinieScale(theMovie) . NULL. 0) ; 


Graphics Mode Tweening 

Let's begin our hands-on work with tweening by 
reconsidering our old favorite, the appearing-penguin 
movie. In the previous article, we built a sprite version of 
this movie by creating a sprite track witli one key frame 
sample (which holds the compres.sed penguin image and 
the initial sprite properties) and 99 override frames (which 
hold data of type MociifierTrackGraphicsModeRecord). We 
constmcted the override samples so that the opacity of tlie 
sprite smoothly increases frcmi total tnmsparency to total 
opacity. This is a textbook case of where tweening can i>e 
of assistance, instead of adding 99 override .samples to the 
sprite track, we can instead add a single tween track to the 
movie that effectively says: start the graphics mode of the 
sprite image at total transparency and smoothly increase it 
up to total opacity, 

A couple of pictures will help us appreciate the 
difference here. Figure 6 .shows the original structure t)f the 
penguin sprite movie. Figure 7 shows the revised version, 
which uses a tw een track in place of the override samples. 



iWlpit! -- 


Sprite taA 


Figure 6: fhe slmciiire of ibe originaljmrgmn sprile morie 



Sprite 


Tweefi ttajtJ: 


Figure 7: 77je stmcture aflhe ra/isedp<.mgHin sprite morie 


Now we need to add a tween media sample to the tween 
track. A tween media sample is an atom container that 
contains one or more tween entries. A tween entry is an 
atom (of type kTweenEntry) that holds other atoms, 
which include at least a tween type atom (of type 
kTweenType) and a tween data atom (of type 
kTweenDaia). Figure 8 shows the general structure of a 
tween media sample. 



Figure 8: Tbe structure of a tween media sample 

The atom data in a tween type atom is the type of the 
tween atom (that is, one of the constants listed earlier). 
The kind of atom data in a tween data atom depends on 
the tween type; for instance. For a tween entry of type 
kTweenTypeGrapliicsModeWiihRGBColor, the atom data 
is a pair of ModifierTrackGiapliicsModeRecord structures 
that specify the initial and final graphics modes. Listing 5 
sliows how we can build the tween media sample for our 
penguin movie. 


The start time and duration of the tween media 
sample determine the start lime and duration of the 
tweening operation. As we'll see later, however, it's 
possiF:>le to limit the tw^eening to only part of the time 
spanned by the tween media sample. 


Ustii^ 5: Building a grapliia» mcxle twe^en media sample 


QTSpi1tcs_AcMTw^etit)veiTidtTmck 

ModifierTrackGraphlcsModeRecord iuyGrapMcsHodG [2]: 

QTAtomCcirLt airier mySample = NULL: 

QTAtom inyTweeiiEntryAtDni = 0; 

myErr = ClTNewAtoiiiGontainer{fi(inySaraple): 
if (myErr != noErr) 
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goto bail: 

// add a tween eiitr>^ atom to the atom eontainer 

myErr = QTInsertChildlraySample, kParentAtomlsContainer, 

kTweenEtitty. 1, 0. 0^ HULL. S:myTweGriEntryAtQm) : 
if (myErr != noErr) 
goto bail: 

// set the t)pe of this tween entry 

myType ^ EndianU32JItoB(kTweenTypeGraphicsModeVithRGBColor); 
myErr * QTInsertChild[mySample, myT'ireenLEntryAtom+ kTweenType, 

1, 0. sizeof(myType). ^myType, HULL): 

if (myErr ]= noErr) 
goto bail: 

// set the initial blend amount (0 = fully transparent) 
myGraphicsMode [0] , grapbicsMo'de “ EndianU32_NtoB (blend): 
myGraphlcsMode[0].opColor.red = 0; 
myGraphlrsMode[0].opColor.green = 0: 
myGraphicsHodeiO].opColoE.blue = 0: 

// set ilie Eiml blend amount (Qxffff = My opaque) 
myGraphicsModeLlJ .graphicsMode= EndianU 32 JltoB(blend): 
myGraphiesMode[ 1 ].opColor.red “ EndianUI 6 _NtoE(Oxffff); 

myG raphic sHode[ 1 ].opCoI d r.green = EndianU 16 _Nt oB(Oxffff): 
myGraphiesModetiJ .opColor,blue^ EndianU 16 _HtoB( 0 xffff): 

myErr = (JfTI na art Chi ld[niyS ample, myTweenEntryAtom, klweenUata. 

1. Q. 2 * aizeof(HodifierTrankGraphicaHodeRecord), 
myGraphiesMode, NULL): 

As you can see, the first record specifies a fully 
transparent graphics mode, while the second specifies a 
fully opaque graphics mode. The tween media handler 
generates a series of records by interpolating the red, 
green, and blue fields. The graphiesMode field is not 
interpolated; rather, it's copied from the first record into 
the tweened record. 

Now it‘s time to add the .sample to the tween media. 
The tween media handler uses the generic .sample 
description, of type SainpleDescription, So we need to 
create a sample description, fill in the descSize field, and 
then call AddMediaSample, as shown in Listing 6. 


Listing 6: Adding a sample to a tween media 


QTSpr i ies_AUd1 'weent Ht rrid 1 1 nick 

// enrate the .sample tk'seription 

mySampIeDeEc ” (SampleBeEcriptianHandle) 

NewHandleClear(sizeof(SampleDGScription)): 
if (mySampleDesc = NULL) 
goto bail: 

(“mySampieDesc} .d 0 scSize = sizeof (SainpleDescription) ; 

// add the tween sample to die iiiedLi 
myErr = BeglnNediaEdlts(myTwGenNedia): 
if [myErr 3^ noErr) 
goto bail; 

myErr = AddMediaSample(myTweenHedia, mySample. 0. 

GetHa ndIe Siz e(myS amp1e), 

GetMediaDuration(GetTrackMedia(theTargetTrack)). 

(SampleDGScriptionHandle)tnySampleDesc. 

1. 0. NULL); 
if (myErr 1= noErr) 
goto bail: 

myErr = EndMediaEdits (myTweenMedia): 


Notice that we specify the duration to 
AddMediaSample like this: 

GetMediaDnration(GstTrackMedia(theTargetTrack)) 

This means that the tw^een media sample extends for the 
entire length of the sprite track (as shown in Figure 7). 
Finally, we need to insert the media into the tween track: 

myErr = InsertNedlaIntoTracktmyTweGnTrack. 0. 0* 

GetHediaDuration (inylVeGnMedla) . flxedl) : 

Setting the Input Map 

WeVe finished creating the tween track, but wc still 
need to link it up with the sprite track so that when the 
movie is played back, the tween track sends its output (a 
record of type ModifierTrackGraphicsModeRecord) to the 
sprite track. The sprite track will use that output to set the 
graphics mocie property of some sprite in the sprite track. 
We indicate both of these kinds of information (the type 
of modifier data the tw'een track is producing and the ID 
of the sprite to apply it to) in the sprite track’s input map. 
We create an input map in exactly the same way we 
did when working with a video override track, by calling 
QTNe w Ato mC o n La i n e r: 

myErr = QTNewAtomContainer (itmy Input Map) ; 

Then we need to add a track reference, from the target 
track (the sprite track) to the tween track: 

myErr = AddTracikReferGnciG(thGTargetTrack. myT^GenTrack, 

kTrackModifierReference, fiiniyReflndex): 

And then we need to add some data to the empty 
input map. QTSpritesPlus calls another application- 
defined function, QTSprites_AddTweenEntryTolnputMap, 
passing in tlie input map, the track reference index 
obtained from AddTrackRefLTence, the ID of the sprite to 
tween, and type of the modifier data: 

myErr ^ QTSprltes_AddTweeDEntryTciInputMap(rayInputHap. 

myRefIndex, kPenguinSpriteAtouiID, 
kTrackModiflGrOhJeCtGraphlt:sMode^ NULL); 

QTSprites_AddTweenEntryToJnputMap is defined in 
Listing 7. It’s pretty much identical to 
QTSprites_AddVideoEntryTolnputMap, except that the ID 
passed in now' specifies the tD of the sprite to which the 
tween data is to be applied, not the image index of the 
sprite. Accordingly, the second child atom we add to the 
input map is of type kTrackModifierObjectlD, not 
k S p ri teP ro p er t y I ma ge I ndex. 

Listing 7: Adding a tween entry to an input map 

QTSpritcs_AddT\veenEntr>'ToInputMap 

OSErr QTSprites_AddTweenEntryToInputNap 

(QTAtomContaiiier thelnputMap. long theRefIndex. 
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lon^ thelD, OSTvpe theType, char ‘theName) 

! 

ifpragnifl unused (theName) 

QTAt om myInputAt om; 

OSErr myEtr = noErr; 

// atkJ ail entry to tlie input rtiap 

myErr = Q,TInsertGhild{theInputMap, kParentAtomJsContainer. 

kTracliModifierInput, theKefIndex, 0, 0. NULL, 
fiiiriy Input Atom): 
if (myErr != noErr) 
goto bail: 

// add two child atoms to the panent atom; 

if tliese atoms define the t^pe of the nmlifier input and tlie D of the sprite to 

// reedve the tween data 

theType = EndlanU32_KtoB(theType); 

myErr = QTInsertChildftheInputMap. myInputAtom. 

kTracldiodifierType, 1. 0, sizeof[OSType), 
^theType, NULL); 

If [myErr 1= noErr) 
goto bail: 

theID = EndianU32_NtoB(thelD): 

myErr ^ QTInsertChlld(thelnputMap* myInputAtom, 

kTrackHodifierObjectID, 1, 0, sizeof(long), 
ithelD, NULL): 

bail 1 

return(myErr): 
f 

Finally, we need to set the sprite track's input map, 
by calling SetMedialnputMap: 

myE r r “ 

SetMedialnputMap(GetTrackMedla CtheTargetTrack) , 
mylnputMap): 


in the previous paragraph, I said that we’ll see '*the same 
sequence of frames’', I was fibbing; in fact we’re likely to 
get a much better visual output with the tween track 
movie than with the override sample movie. Smaller and 
better; ain't life grand? 

Matrix Twei^ning 

Now that you're convinced that tween tracks are w^orth 
playing with, let’s consider a few' more examples. In the 
previous article, we changed the horizontal position of the 
icon sprite by adding a bunch of override samples, each of 
which contained a matrix record specifying a new' position. 
Once again, we can replace all those override samples with 
a single tween track, which contains the initial and final 
matrices. At run lime, the tween media handler generates 
the intermediate matrices and funnels them to the sprite 
media handler, which applies them to the sprite to achieve 
the horizontal motion. 

BuHding the Tween Data Atom 

Listing 8 shews the code that we use to build the 
tw'een data atom in the media sample for the tween track. 
The atom contains tw’^o matrices, one for the initial position 
of the icon sprite and a second for its final position. Note 
that the matrices are just concatenated together as the atom 
data, not inserted into separate atoms. 


’Voila, we’ve just created our first tween track and 
linked It to the sprite track. If we save the movie io disk 
(by calling AddMovieResource and CloseMovieFile) and 
then reopen and play it, we'll see the same sequence of 
Frames that we saw^ when playing the original penguin 
movie or the original sprite version of the penguin movie. 
There are, however, several important advantages to 
using a tween track in place of sprite track override 
samples. First of all, since we have stored only two 
ModifierTrackGraphicsModeRecord structures instead of 
99, we can expect to see some reduction in the size of the 
movie file. In fact, the size of the penguin movie file is 
reduced from 36 kilobytes to 28 kilobytes (almost one- 
quarter smaller). 

The second important advantage to using a tween 
track is that it has no pre-established frame rate. In the 
override sample version of the penguin movie, well get 
at most 10 frames per second, because we have 100 
frames in a 10-secoiid movie. (I say “at most” 10 frames 
per second because QuickTime might need to drop some 
frames if the user's computer is not capable of displaying 
10 frames per second.) With the tween track version, we’ll 
get as many frames per second as QuickTime and the 
accompanying hardware can manage — w^hich should 
easily surpass 10 frames per second, (Indeed, on a mid¬ 
range F^ow^erMac G3 t 1 clocked the tween version of the 
penguin movie at a brisk 83 frames per second!) So when. 
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Listing 8: Building a matrix tween media sample 


QTSprites^AddTweenQverriUcTrack 

HatrixRecord myMatrix[2] : 

// set the initial dati for tliis tween entry 
SGtIdentityMatrix(SLniyMatrix [0]) : 

TranslateHatrix(6imyHati:ixl0] * 

LDng2Flx(kIconDiiiiension + (kIconDiinension / 2)), 
LDng2Fljc(kIconDi]iien£lon + (klconDimension / 2))): 
EndianUtilsJlatrixRecordJJtoB (fiiniyMatrlx[0] ] : 

// set the tinal dm for tills tween entry' 

Set Id entity Mat rixC&my Hat rixflj): 

TranslateHatrix(6£myMatrix[l] » 

Long2Fi)c(230 + [klconDimension / 2))» 

Long2Fix (klconDimension + (klconDimension / 2))): 
EndianUtlls_MatrixRecordJJtoB(&myMatrix[l]}; 

inyErr = QTInsertChild(mySample. myTweenEntryAtom, kTweenData, 

1* 0, 2 * sizeof[MatrixRecord)t myHatriXi NULL): 

The tween track is built exactly as above; the only 
difference here is that the modifier input type is 
kTnickModifierObjectMatrix- Once again, the resulting 
movie file is smaller than the version tliat contains 
override samples. Also, thanks to the increase in frames 
per second, the movie playback is nt)iiceably smoother 
than the override samples version. 


Setting the Tween Offset and Duration 

As weVe seen, a tween operation begins at ilie start of 
a tween media sample and extends for the entire length of 


the sample. It's possible, however, to add a couple of atoms 
to a tween entry atom to modify this default behavior. 

[f we w’^anr a tweening operation to begin at some 
time after the start of a media sample, we can include a 
tween offset atom, of type kTweenStartOffset. The data 
for a tween offset atom is a value of type Time Value that 
indicates how far into the tween media sample the 
tweening operation is to begin. (This value should be 
specified in the media's time scale.) If theSample is a 
tween media sample atom container and my Atom is a 
tween entry atom, then we can add a tween offset atom 
to that tween entry atom like this: 

theOffset = EndianS32_NtoB[theOffset): 

myErr = QTInsertChild(theSample. myAtom, kTyeenStartOffset♦ 

1. It sizeof(TimeValue), fictheOffaet, NULL): 

The index and ID of the tween ofkex atom must both be 1. 

If we want to modify^ the duration of a tweening 
operation, w'e can add a tween duration atom, of type 
kTweenDuration, to a tween entiy atom. The data for a 
tween duration atom is a value of type TimeValue. We can 
add a tween duration atom to a tween entry atom like this: 

theDuration = EndianS32_NtoB(thBDuratinn): 

myErr “ QTInsertChild(theSample, myAtom. kTweenDuratlon, 

1. 1„ sizeof {TiTneValuc) K fiftheDuratlon, NULL): 
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Once again, the index and ID of the tween duration atom 
must both be 1, The file QTSpritesPlus.c defines two 
functions, QTSprites_SetTweenEntryStartOffset and 
QTSprite5_SetTweenEntry Du ration, that you can use to 
set a tween’s offset and duration. 

Spin Twebning 

Suppose now that we want a sprite to spin around in 
the sprite track. The standard way to get a sprite to spin 
is to include a large number of sprite images in the key 
frame sample and to change the sprite's image index 
during playback. (See the '‘space movie” created l>y last 
month's sample application.) Or, we could try to use die 
matrix tween just discussed, in conjunction with the 
RotateMatrix function, to set up a rotation matrix for the 
sprite. It turns out, however, that this is trickier than you*d 
suspect. If we wanted to rotate the icon one full turn, we 
might think w'e could specify a final matrix like this: 

EetI<ientityMatrix(&iiiyHatrlK[i]): 

RotateMati:ix(SmyMatrix[l] , LoTig2Fix 1360) , 0. 0); 

But that won't do at all; 360' is the same position as 0\ 
so the resulting tween w^ould effectively do nothing. Worse 
yet, it\s not clear hew we'd .specify rotating two or more 
times. No doubt we could chop things up into a number of 
smaller rotations, but that's getting unduly messy . 

To allow' us to easily spin an object an arbitrary 
number of rotations, Quick'l'ime 3-0 introduced spin 
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rw'cening. The tween atom data for a spin tween consists 
of tw'o Fixed values, die initial rotation amount and the 
total number of rotations. Listing 9 shows part of our code 
for building a tween track sample that spins the 
QuickTime ictin kNumRutation.s times (which is defined 
in QTSprite.sPlus.h as 5)- 


Listing 9: Building a spin tween media sample 

QTSprit^j^ddTweenOvemdeTracl! 

Fixed mySpinBata[2]r 

// set the initijil rotation value 
jnySpinDflta [0] = EndlanU32_NtoE (0) ; 

// set the number of rotations 

mySpinDatafl] = EndianU32_NtoB(Long2Fix(kNumRotations)); 

myErr = QTIns art Child f my Sample, tnyTwaenEntryAtoxi. kTweenData, 

1, 0. 2 * sizeof(Fixed), crySpinData. NULL); 

The output of a spin tweening operation is a matrix 
(of type MatrixRecord) that can be applied to a sprite to 
achieve the desired rotation. The point of rotation (that is, 
the point about which die sprite image is rotated) is the 
image's registration point, which is set at the time the 
sprite image is added to the key frame. Note that the 
registration point is nt)t a sprite property and cannot 
therefore be changed dynamically. Rather, the registration 
point is a property of the sprite image. The default 
registration point is (0, 0), or the upper-left corner of the 
box surrounding the sprite image. 

Figure 9 shows a .sprite movie in which the 
QuickTime icon rotates about the default registration 
point. Notice that the icon is now located at track position 
(0, 0). That's because the matrix generated by the spin 
tween overrides the matrix in the key frame sample (with 
which we specified the desired position of the icon). 



Figure 9: A sprite spinning around the default 
reg istra t io n po i n t 

When we mn the movie, the icon spins around the 
point (0, 0), which means that it keeps moving in and out 
of the movie box. Now that’s goofy. 

Let's move the registration point of the icon image to 
the center of the image, like so: 
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royPolnt.x = Long2FiK(kIcoiiDiiQecsion / 2): 
myPoint.y ~ Long2FlxfkIcoiiDiiiiansioi:i / 2): 

// ^dd images to the key frame sampJe 

Spi:itetltils_A[ldPICTlMageToiCeyFratiieSa]iipie fmy Sample, 

kOldQTIconlD, AmyKeyColor, 1. &myPoint» KULL): 

Tills gives us a movie that's slightly lietter, but still not wholly 
satisfactory (See Figure 10,) The icon is still saick in the 
upper-left comer of the movie box. What we’d like, 1 think, is 
for tlie icon to lie situated at some other location in the movie 
box and spin around its registration point at tliat location. 


Notice that the tw^een data atom of the multimatrix 
tween entry is a parent atom that contains two tween 
entry atoms, one for the tween that spins the sprite image 
and one for the tw'een that translates the sprite image. 

Listing 10 gives the code we use to add atoms to a 
parent atom CmyTweenEntryAtom) to build a multimatrix 
tween atom. Matrix operations are not in general 
commutative, so the order in which we add the tween 
entry atoms for the matrix tweens to the multimatrix 
tween data atom is important. In Listing 10, we add the 
spin tween and then the translation tw^een. 



Multimatrix Tweens 

What we need is to tie able to generate a matrix that both 
traaslates and spins the sprite image. This is a job for the 
multimatrix tween, intrcxluced in QuickTime 3 0- A multimatrix 
tween concatenates two or more matrices produced by other 
kinds of tweerLs. To create a niultimatrix tween, we build the 
atoms for the individual tw^eeas and then add tliem to the data 
atom of a multimatrix tw^een entry. Figure 11 shows the atom 
structure that we want to build. 



Figure 11: A muhimatrix tween that translates and spins 


Tlstifig 10; Buildi ng a imiltlinAtrix tw een media s ample_ 

QTSpritcs_Ad(mveenOvemdeTrack 


QTAtojn 

OTAtoni 

MstrixRecord 

Fixed 


rnyMiiltiTweenDstaAtcim = 0; 
myAtora = 0; 
myKatrix[2j : 
mySpinData[2]j 


// add a ftiultimatrix tween data atom to the m^een entry atom 
myErr = QTInBGrtChild(mySample* myTweenEntfyAtorni kTveenData, 
1, 0, 0* NULL* SirnyMyltiTweenDat^toni): 
if {myErr !“ noErr) 
goto ball: 

// add a spin tween to the multimatrix tween data atom 

myErr = QTInsertChild (mySample* rnyMultlTweenDataAtom. 

kTwGGDEntry, 1< 0< 0* NULL* StnyAtom); 

If (myErr noErr) 
goto bail: 
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// set the type of this tween entry 
nryType “ EndiaiiU32_NtDB(kTweenTypeSpin); 
myErr = QTInsertGhild(mySample. myAtom. ETweenType, 1, 0, 
sizeof(myType). fiimyType, NULL); 
if (myErr 1= noErr) 
goto bail; 

// set ilTe initial rotation value 
mySpliiData[Oj - EiidianU32_NtoB(0) j 

// SCI the number of stations 

mySpinData [Ij = EndianU32_NtQB (LongZFix(kHiiioRcitations)) : 

utyErr ^ GlTInsertChild(mySample. myAtom, kTweenData. 1, 0. 

2 sizeof (Fixed), mySpinData* MJLL): 
if (myErr f= noErr) 
goto bail; 

// add a translation matrix tween to tltc multimairix tween data atom 
myErr = QTInsert Child (my Sample. rnyMultlTweenDataAtom* 
kTweenEntry, 2, 0. 0* HULL. ^lyAtoiii): 
if (myErr !" noErr) 
goto bail: 

// set the type of this (w^een enby^ 

myType ^ EndianU32_NtoB[kTweenTypeMatrix): 

myErr = QTInsertChild(mySample* myAtom, kTveenType. 1. 0. 

sizeof (myType) * isinyType* NULL): 
if (myErr ]“ noErr) 
goto ball: 

// set die initial data for tliLs tween entr>' 

SetIdentityMatrix(&myHatrlx [0]): 

TranslateHatrix(&myMatrix[0] * 

Long2Fix(kIconDimension i (klconDimension / 2))* 
LQng2Fix(kIccmDinienslon + (klconDlmension / 2))); 
EtLdianUtils_MatrixRecord_HtoB (SmyMatrix [U ])) 
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U set tlie final data for this tween entr>' 

SotIdentltyMatrlx(£imyMatrix [1]): 

TranslateMatrixt&myMatrix[l]. 

Long2Fix(230 + (kIconDinsension / 2)}* 
Long2Fix(kIccinDimeni3ion + [klcoriDimension / 2))); 
EndiajiUtilEjiat.rixR&cord_NtoB(imyMatrix[l]): 

myErr = QTInsertChild(mySample* myAtom. kTweenData* 1* 0* 

1 * sizeof(MatrixRecord). myMatrix. NULL): 


Figure 12 shows a frame of the resulting movie, in 
which the icon rolls its way from left to right. Now that’s 
extremely goofy. 



Conclusion 

Video override tracks and tween tracks provide 
two different ways for us to enhance our sprite movies* 
Video override tracks give us a way to tap into an 
existing video track as a source of images for a sprite; 
they are kind of a one-trick pony, hut nonetheless 
useful in the right circumstances. Tween tracks, by 
contrast, are quite generally usefui; they give us a way 
to aigorithmicahy alter sprite propertie.s without using 
override samples. Tween tracks have the added 
benefits of smaller file sizes and increased frame rates. 
They are also usually easier to construct than a 
sequence of override samples. Why, after all, should 
we bother to do the math tc^ figure out how to fade 
from full transparency to full opacity? Let*s just let the 
tween media handler do it for us. 

In the next article, weTe going to consider yet 
another way to enhance our sprite movies, by 
attaching wired actions to the sprites. Our goal is not 
only to make our sprites active (using override samples 
or video override tracks or tween tracks), but also to 
make them interactive. Mi 
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By Larry Taylor 


A Postscript IDE via a BBEdit Plug-In 


Using BBEdit + Distiller + Acrobat to 
create postscript files with a 
minimum of fuss 

Introduction 

Seven or eight years back^ MacTech devoted an issue 
to the postscript page description language and neat 
things that you coukl do with it (VoL 9, 1993, Issue 4). 
This briefly inspired me to try some things Vd wanted to 
do, hut the lack of any sort of programming environment 
WAS a real hindrance - sending your code to a printer and 
wailing to see what happens is slow, frustrating and a big 
w^aste of paper. When Adobe came out with Disliller, life 
improved some. Ycm could write your code using a text 
editor (such as BBIidil), open the file in Distiller iind then 
read the resulting pdf file using Reader, All in all^ not too 
bad. This got me doing postscript programming again, but 
it wasn’t a true Mac experience. Ideally, I wanted to l>e 
able to type some code, execute some key combination 
that compiles the code, and then execute another key 
combination and have the results displayed. 

In volume 14, 1998, Issue 6, MacTecb had an article 
on BBEdit plug-ins by Stevie Sheets. I read the article with 
some interest, but as all of his examples dealt with 
manipulating text in BBEdit windows, nothing clicked and 
1 passed on, Then one day it occurred to me that there 
must be commands for file manipulation as w^ell. After all, 
there is the old chestnut ''Send Postscript" that I had first 
used to send niy postscript files to the printer. It ought to 
be possible to write a plug-iii to mimic '‘Send Postscript" 
but using Distiller and Acrobat instead of a printer: 
specifically, a plug-in with the following behavior. 

Take the text in the front window and find the associated 
file. Use some aile to asscKiate a pdf file to BBEdit file and 
find it. If the modification date on the pdf file is older diati 
that on the BBEdit file, send the BBEdit file tc^ DistiHer; 
otherwise send the pdf file to Reader or Acrobat. 


The rest of this article describes such a plug-in and 
how you can code it and get it working. I will try to 
duplicate as little of Steve Sheets’ anicle as possible, 
subject to this article's being self-contained, so for a 
detailed discussion of how BBEdit plug-ins work, go read 
Sheets’ article. 

Caveats and Quibbles 

I have used this plug-in for several months but it is not a 
commercial quality postscript development environment. It 
works quite well for small projects and I recommend it fcjr 
doing eps files. If you would like a postscript file to start on, 
http://www.nd.edu/~taylor/ComputerStuff/Postscript/gfaphpaper.htnil 
will get you a simple postscript program lor graphing 
functions together with some additional examples. 

Here are a some minor annoyances and their work-arounds. 

1 You have to invoke the plug-in twice to get from 
changes in your postscript code to the displayed pdf 
file. Live with it. 

2 If you leave the pdf file open in Acrobat and try^ to 
distill the BBEdit file again, Distiiler puts up an error 
message that it can’t delete the pdf file and halts. Just 
close the pdf file and try again. 

3 When you invoke the plug-in the application being 
called comes to the foreground. You need to get back 
to BBEdit to run the plug-in again. Since the Dfstiller 
window is small, a simple mouse click will do the 
trick. Since any error messages you may generate 
appear in the Distiiler wandow, it is actually a feature 
to have it foremost. The Acrobat window is usually 
large and getting back to the BBEdit window may 
involve more than just a mouse click, but this is also a 
feature since it encourages you to close the Acrobat 
window' before doing more work on your code, thus 
avoiding annoyance 2”. 


The author Is a research mathematician and profe^or who spends too much lime fooling around with this sort of tiring. More smT at 
< w w w. nd. ed uZ-tay lor>. 
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First Steps 

If you have never programmed in C iDefore, this may not 
be a good initial project, but if you are reasonably familiar 
with your C compiler you should be able to complete this 
project. I use CodeWarrior as my C compiler so my remarks 
will apply precisely to their setup but only minor 
modifications should be needed for other environments. 

You need the BBEdit Extension SDK. This can be 
obtained from the BareBones website via 
http://www.barebones.com/suppofi/developer/pluginsdk.html and 
follow the link. When un-stuffed, you will have a folder, 
BBEdit Extension SDK, with three folders and two files. 
The file Writing BBEdit Extensions, srd is a stand alone 
document describing the subroutines available to you, 
their argLunent structure and what i.s returned. It also has 
specific suggestions to help you get your Code Warrior ox 
Symantec environment working. 

My suggestion is to go immediately to the examples, 
find HelloWorld and compile it. In my case, CodeWarrior 
wanted to update to a newer version which came off 
without a hitch, and then a few paths had to he reset. After 
these annoyances, the project compiled and when the 
plug-in was added to the BBEdit Support:PlLig-Ins folder, 
the project worked as advertised. HelloWorld is an 
excellent project to start with since once you get it 
working, the alterations necessaiy for this project are 
mostly a matter of making a few^ changes and adding code. 

The Actual Code 

The code below was produced a.s ff>llc>ws. first 1 
made a copy of the working HelloWorld project and 
renamed all the files Postscript!DE.whatever. Then I 
opened the Postscript!DE.rsrc file and added an alert with 
one button to dismiss the alert and one static text box 
with an entry of Afj. The resource ID of the alert was 12H. 
Then the project file Postscript!DE.p was opened. Once in 
CodeWarrior I opened the l^ostscripLlDE Settings dialog, 
selected 6EK Target and changed the Rescnirce Name to 
PostscriptIDE. The name liere" becomes the name the 
plug“in has in the Tools menu in BBEdit. The file.s in the 
project still had their flelloWorid names so I deleted 
HelloWorld.c and HelloWorld.rsrc and replaced them with 
their PostscriptIDE counterparts. 

Next I opened the Postscript!DE.c file and deleted all 
the code between the EnterCodeResource(> and the 
ExitCodeResource(). The Enter/Exit routines must blanket 
our code in order to correctly interface with BBEdit, so 1 
left them. One also needs to be careful, especially with 
error handling, not to return contrtjl to BBEdit without 
going through ExitCodeResource(). Finally, I added code 
to produce the program you see below. 


The code in main is straightforward. A pointer to tlie 
front wind<w is one of die variables we are handed when 
our cckIc starts up and we check first that it is not NULL and 
if it Ls not, then we make sure we have a w^indow of kind 
userKind since all the subsequent calls to the BBEdit 
subroutines that we use warn that they should only be called 
on windows of kind userKind. If either of these tests fail, we 
put up our alert and when the user dismisses it, we return 
control to BBEdit via the ExitCodeResourceO routine. 

The call to the subroutine bbxtGetWindowContenls() 
returns a handle to the contents of the front window. 
Assuming this works, we check that the file starts with 
!%PS, since any legitimate Postscript file must start this 
way. tf this fails, we put up our alert and again exit 
gracefully. If our check is successful, then we get the file 
information associated to the front window. Assuming we 
get a valid file, we turn our information into an FSSpec 
for the file and call the sufirouiine Ship_to_APPL which 
does most of the work. If we fail here tlicTe are two 
po.ssibilitlcs. There may be no file to get, if for example 
we have nol yet saved it. In this case we put up an alert. 
We also might fail to create the FSSpec from the data 
BBEdit retLirn.s. We consider this unlikely but put up the 
BBEdit alert box for handling this," 

Next come the declarations for two subroutines. The 
subroutine FSpGetHPBRec takes an FSSpec pointer and 
fills in an HParamBlockRec for the file which lets us get at 
the modification date. Tire subroutine Calcuiate_pdfJife 
takes an FSSpec pointer to the BBEdit file and returns an 
FSSpec pointer to the pdf file. 

The Ship_to_APPL suhroutine dties the real work. 
First we calculate the name of the pdf file from that of the 
BBEdii file by calling our subroutine. Then we try to get 
ihe 1 HParamBlockRec for the pdf file. If this fails, we 
prepare to ship the B]?Edit file to Distiller liy setting Res 
to q^STL', the signature for Distiller, anci file to point to 
the Bl^Edit file. If we get an HParmBlockRec for the pdf 
file, then we also get one f(jr the BBEdit file and compare 
the modificalion dates. (If w^e fail to get the modification 
date for the BBEdit file we pul up the standard BBEdit 
alert.) Depending on how^ the modification dates 
compare, we set to ‘DSTL' and fhe to point to the 
Bf5Edit file or else we set Res to ""CARO’ and Ol^ to point 
to the pdf file. (An annoyance arises here - CARO' is the 
signature for b(jth AcroIxiL and Reader so which of these 
will be used to open the pdf file depends on your setup. 
Find any pdf file and d(>LibIe click it. Whichever 
application opens this file will be used by this plug-in.) 
Finally, w^e call bbxtSendOpenDoc() which opens the file 
pointed to by file in the application with signature Res, 
Again, this routine can return an error and we just pass it 
to the BBEdit alert. 
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The code for the two subroo tines is straightforward. 

• FSpGetHPBRecO just sets some entries in the 
HParamBlockRec and then calls PBHGetFInfoO which 
fills in the HParamBlockRec for us. Whatever error 
code we get, we return. 


• Calculate_pdf_file takes the FSSpec for the BBEdit file 
and produces an FSSpec for the .pdf file by stripping 
off a .ps, eps or .epsf ending if there is one and 
appending .pdf. We do check that the file name will 
not be too long and truncate if necessary. The volume 
and parent directory for the pdf file are the same as 
for the BBEdit file. 

The code. 

Tine first part is in small type so that ii tbrmats idcnUcally to the first 
part of the file HeUoWorld.c.The rcguliir font size denotes code that has 
been changed from this file after the deletions discussed above. 

^include <ExternalIrLterf ace - h> 

// deal withA4 

#ifdef THINK_G 

#include <SetupA4.h> 
f/define EnterCodeResource () do f 
ReuemberAOO: SetUpA4(): ) while (0) 

#define ExitCodeResource() do I RestoteA4(): 

1 while (0) 

//end if 

//ifdef _HWERKS_ 

//include <A4St’Liff.h> 

//endif 

//define ALERTID 128 

void Ship_to_AFPL ( ExternalCallbackBlock *ciallbacks. 
FSSpec* file); 

pascal void main(ExternalCalIbackBlock ‘callbacks. 

WindowFtr w) 

I 

Str63 ml=^‘*\pThe front BBEdit window doea not 
start with'’; 

Str63 tn2=”\p 'iilPS on the first line.'': 

Strl5 m3=”\pNo file found - 

Str63 m4="\pprobably need to save first !'*: 

Str2 55 fI^ame: 
short vRef; 
long dirlD; 

FSSpec file: 

OSErr err: 

Handle window_text: 

EnterCodeResourceC); 

if (wt=0 ([WindowPeek)w)->windowKind==userKind) I 

window_text*=hbxtGetyindQwCc>ntent.a (callbacks * w) : 
lf( window_text!-0 fiific 

* ((long*) *window_text ) = '% ! PS ' ) I 

/’Force window text to start with %!PS 7 

bbxtGetDocInf0(callbacks.w,fName,&vRef. ficdlrlD): 
if (fNanie[0] 1=0) I 

err=FSMakeFSSpec(vRef.dirlD.fName * &file); 
if(err==noErr) [ 

Shlp_to_APPL, (callbacks . fitfile) ; 


else ( 

bbxtReportOSError(callbacks.err); 

I 

1 

else f 

ParamText{m3,m4."\p”."\p"): 

Alert(ALERTID.bbxtGetStandardFlIter (callbacks)) : 

) 

1 

else [ 

ParamText (ml. tii2 . ” \ p” , " \ p ” ) ; 

Alert(ALERTID.bbxtGetStandardFilter(callbacks)); 


else ( 

ParamText(ml.m2."\p"."\p”): 

Alert(ALERTID.bbxtGetStandardFilter(callbacks)): 

1 

ExitCodeResource0; 

I 

OSErr FSpGetHPBRec (BPartnElkFtr . FSSpec ‘: 

void Calculate_pdf_file(ESSpec ‘pdf_file. FSSpec 

*ps_fiie): 

void Ship_to_APPL( ExternalCallbackBlock *callhacks. 

FSSpec* p3_flle) 

! ESSpec pdf.file. *flle: 

HParamBlockRec ps. pdf; 

OSErr err; 

03Type Res: 

Calculate_pdf_f ile (£tpdf_f ile , ps_file) ; 

err"FSpGetHPBRec(&pdf,&pd f_flie) : 

if(err!=noErr) i /* If no pdf_file ship to 

Distiller.*/ 

Res='DSTL':flle“ps_flie: 

) 

else ( 

err=FSpGetHPBRec(fiips.ps_file): 
if (err“noErr) \ 

/* If thrre is such r file, 

get modification dates for ps_file and pdLhlc V 
/“ If date for pdGfile is later, send pdf_file to Reader, 
otherwise send ps_file to Distiller V 
iff (unsigned long)pdf *fileParam.ioFlMdDat 

(unsigned long)ps,fileParam.ioFlMdDat ] f 
Res='DSTL^;file-ps_f1le: 

! 

else f 

Res“'CAR0' ; file=6[pdf_flie : 

I 

) 

else [ 

/*This should not happen 17 
bbxtReportOSError(callbacks,err): 
return: 

1 

I 

err=bbxtSendOpenDoc(callbacks.Res,0 * file.trueJ : 
if (err \ “iioErr) i bbxtReportOSError (callbacks , err) : 1 
I 

OSErr FSpGetHPBRec(HParmBikPtr hpbp. FSSpec* file)f 

bp bp - >f ileParam. ioVRefNiim=f lie - >vRefNum: 

hpbp->fileParam.ioFDirIndex=0: 

hpbp->f ileParatn, ioNamePtr=file->name ; 

hpbp ->fileParam. ioDlrID“f i le - > par ID 

return(PBHGetFInfo(hpbp,false)): 


void Calculate_pdf_flie(FSSpec *pdf_flle. FSSpec 
*ps_flle) \ 
short rr: 

Strl5 offset; 
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*pdf_file“*pa_f±ie: 

rr=of fset [C}]=pdf_file->name [O] : 

offset[1]=offset[0]-1:offset [2J =offset[0] -2 : 

offset[3]“offset[0]“3:offset f4]=offset [0]-4; 

if{ pdf^file’>name [offset [2] ] 

pdf_f lie - >naTiie [offset [ 1 ] ] = *p ' 
pdf_file->naine [offset [0] ] = 's ' ) ( 

r r=pdf_file’>naiiie [0] -3 ; 

) 

else 1f C 

pdf_f lie' >naine [offset [4] ] ==’ . ’ Si fit 
pdf_flle->iiame [offset [3] ]^' e ' &£e 
pdf_f lie - >name [offset [2] l = ’p * && 
pdf_file' >name [offset [l]] = "s' && 

pdf_flle->name [offset [0] f' ) t 
tr^pdf_file->narae [ 0 ]- 3 ; 

1 

else if( 

pdf_file->name [offset [3] ]=^‘ »* 
pdf_file->T3ame [offset [2] ]=='e* && 
pdf_file->name[offset[1]]="p" && 

pdf_flle->name [off set [0] ] = 's' ) f 
r r=pdf_file- >naine [0] - 4 : 
i 

if{rr>27) [rr=27:1 

pdf_.f ile- >name [O] =rr; 

pdf_flie ->name[++pdf_flie->name[0]I ="*' i 
pdf_file- >name [++pdf_file->nanie [ol ] = 'p ' : 
pdf_file‘ >name [++pdf_flle’>nanie [0] ] = *d ' : 
pdf_flie ->name[f+pdf_file->name[0]] = 'f' : 

) 


Conclusion 

Alter compiling the project, drop the file into the 
BBEdtt Support:Plug-lns folder and restart BBEdit. 1 like to 
add a key stroke combination to run the plug-in. To do 
this, select Tools List from the Tools menu, select your new 
plug-in, click on the Set Key button and type the desired 
key stroke ct)mbination. 

This plug-in turns BBEdtt Sl DistiHer & Reader into a 
workable postscript deveiopment environment. Several 
thing.s are missing from an ideal environment, mostly in 
the debugging line. Under die current scheme, it is 
Dtstiiler that would have to supply the debugging 
capabilities and at the moment such capabilities are 
minimal. This article is not the place to discuss postscript 
programming, but the green book, FosL'^cript Language 
Program Design (ISBN 0-201-l4396“B, 1988, Addison- 
Wesley), has a very useful section on debugging. In 
particular, its message routine 


/njsgl 

print {\ii} print flush 
I bind def 


can be used to print messages to the Distiller window- 
such as 

(Yea! We got here*) msg 

which can be used to locate the source of difficulties ^— 
not ideal but wwkable, as many of us old guys can attest 
from much debugging in many different languages. Bd 
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MAC OS X 


By Andrew C. Stone 


Help On The Way! 


A guide for the perplexed on 
adding Apple Help to your OS X 
application 


A really well-designed applicalion shoulcJn’t require 
a help system, bul no application is truly ready to ship 
unless it has coniprehensive, online, at the user’s 
fingertips, Help, Furthermore, a cardinal rule about Help 
is "the programmer should not write the Help.'’ Ideally, 
the Help authors are normal human beings who can 
write simple concepts in plain sentences, not coders w ho 
think recursively in an obfuscated manner! Step One: get 
stmieone else to write the Kelp! 

We have a saying here at Stone Design regarding 
hetp: “if it's hard to explain, then iFs wrong.” The process 
of creating Help can provide excellent feedback on the 
user interface and core “mental model'’ {)f your software’s 
architecture. Too often, Help is left for last, and then it’s 
too late to incorporate solutions to the problems 
uncovered by having to explain how^ to do a task. 

This article will explain how to add help to your OS 
X application, both comprehensive, searchable Help 
through the use of the Apple-provided companion 
application “Help Viewer,” and the simple User Interface 
’"Tool Tip” help that pops up a small window' when you 
leave your mouse over a centred for a few seconds. A 
third, intermediate form of Help is context sensitive 
menus and associating longer rich text files wuth 
interface components, but we’ll leave that as an exercise 
for the reader. 

Tool Tip: Don’t foi^et your umbrella when it rains 

The simplest form of Help is Tool Tips — and since 
users are often confounded by interface controls, you 
should always provide these. Interface Builder, a 


pow^erful user interface building application which now^ 
supports both Carbon and Cocoa development 
environments, makes adding Tool Tips easy. 


Stroke 



Antiallas 0 



Q Use Neo 


click and drag to set line width i 


Help Tips ixp up ivhen leave your mouse owr a control 

1, Open your nib files in Interface Efuilder 

2, Select a coiiuol 

3, ik ing Lip tlie Info panel: Ttjols -> SIk)w Info 

4, Select Hlelp’’ from the popup button U) load the Help pane 
3, Enter your Help tip 

6. IMPORTANT: Type <RI:TURN> to make sure the Help tip sticks! 



You add help lips direclly in Interface Builder 


Andrew Stone is chief crystal gazer at Stone Design, www.stone.com, and has been coding in Cocoa as an independent software developer 
for over 13 years. 
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“Wi/fcowf a doubtf the Premiere Resource Editor 

for the Muc OS .•< A wealth of time-saving tools.^ a 

- Mac User Magazine Eddy Awards ^ 

'A distinct improvement over Applets ResEdit.^ 

- MacTech Magazine ^ 

'Every Mac OS developer should own a copy of Resorcerer'' 

- Leonard Rosenthal, Aladdin Systems 

''Without Resorceren our localization efforts would look like a 
Tower of Babel. Don't do product without it!" 


- Greg Galanos, CEO and President, Metrowerks 


"Resorcerer's data template system is amazing" 

— Bill Goodman, author of Smaller Installer and Compact Pro 

"Resorcerer Rocks! Buy it, you will NOT regret it" 

“ Joe Zobkiw, author of A Frcggment of Your Imc^ination 

"Resorcerer will pay for itself many times over in saved time and effort" 

- MacUser review 

"The template that disassembles PlCT's is awesomeF A 

- Bill Steinberg, author ofPyro! and PBTools 

"Resorcerer proved indispensihle in its own creationr 

- Doug McKenna, author of Resorcerer 




Version 2.0 



• Very fast, HFS browser for viewing file tree of all volumes 

• Extensibility for new Resorcerer Apprentices (CFM plug-ins) 

• New AppleScript Dictionary (*aete’> Apprentice Editor 

• MacOS 8 Appearance Manager-savvy Control Editor 

• PowerPlant text traits and menu command support 

• Complete AIFF sound file disassembly template 

• Big-, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 


Requires System 7.0 or greater, 
h5MB RAM, CD-ROM 


Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it’s easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-hased, design and operation 
All file information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rez-like scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linxing Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, 'ictb’s, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PO s, or Visa/MC 
Taxes: Colorado customers only 


Extras (call, fax, or email us): 
COD, FedEx, UPS Blue/Red, 
International Shipping 


ihic editors support screen-copying or partial screen-copying 


MATHEMiESTHETICS, INC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
re sor cerer@m athemaesthetics. com 


Ib order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website^* 


www.mathemaesthetics.com 














Sometimes you may have to have a larger amount of 
text to adequately explain a certain control^—here's a tip 
for you- to make multiple line help tips, insert an 
<OPTION-RETURN> between lines. In fact, this same 
technique is useful in any application where you have a 
standard textfield and you want to add a <RETURN> or 
a <TAB> to the contents of the field. Normally, textfieids 
are set to *'end editing” when the user types a 
<RETURN> or a <TAB>. The workaround is to hc^ld 
dowm the Option key while you are typing the 
<RETURN> or <TAB>. 


f 


Complicate! ^ ButtorT^ 

When you press this bunon, 
all sorts of neat things will 
start to happen - that's why 
we*re explaining that here! 


You can make multiple ime help tips ivitb <Option-RElVRN> 


If you read the documentation on setToolTip;, you 
can see that it’s a method implemented by NSView^ and 
all of its subclasses. This is fine until you go to provide 
Help for cells in an NSMatrix—Interface Builder only 
allows you to set one tip per view. Yet NSMatrix declares 
a method - (void)setToolTip:(NSString *)toolTipString 
forCell:(NSCell '^)cell, so obviously it’s possible tcj add a 
tool tip to each of the cells. Hopefully, the hardw^orking 
IB team will add an easy way to add tips to cells, hut 
meanwhile, you can dcj thi.s programmatically. Ftir 
example, if you have a dynamically loaded tool palette 
matrix, where each cell represents a Cla.ss to instantiate 
wdien its selected, you could do something like this: 

unsigned i.ci 

unsigned rows = [toolHatrix numberOfRows]; 
unsigned cols = [tnoLMatrix numberOfColumns] i 
for (r = Dr r < rows: r-l-+) [ 
for (c = 0; 0 < cols: C++) ( 

tJSButtonCell *cell = [toolMatrix cellAtRow:r coluiDn:c]; 
Class theClass = tepresentedObject]: 

if (theClass) ItoolHatrlx 

setToolTlp^MSStringFromClassCtheClass) forCell;cell]; 

1 

I 


If your class names are nor meant for human 
consumption, like SKTlmage, then each of your tool 
classes could return a method, + 
(NSString^)humanReadabieName, and you'd replace 
NSStringFromClass(theCiass) wnth [theClass 

humanReadableName] above. 


Comprehensive Help and Apple Help Viewer 

Whether your application is a full blown desktop 
pLiblishing package or a simple utility, you should always 
include uSearchable help. And die folks at Apple have tried 
to make that easy by providing Help Viewer—stand 
alone application that gets called to load your "Help 
Book.” Making a Help Book has a number of steps and a 
few gotchas, so let's go over the process step by step. This 
is meant as an introduction and quick start. Full 
documentation on the subject is available from Apple at 
http://developer.apple.com/techpubs/macosx/Carbon/Humantnterfac 
eToolbox/AppleHelp/AppleJelp/index.html, 



To?/ gel Sherlock searching capabilities in Help Viewer 


1, Write your help in HTML 

First, you II need to create the w^eb pages that 
represent your help in HTML V3,2 - later features may 
not be supported in Help Viewer, Of course here at 
Stt5ne Design, we use Create® because it allows us to 
create content in a page lay out/web authoring system, 
and then it automatically generates tlie interconnected 
web pages. Tins allows us to add more content later and 
not worry about the HTML, However you make your 
pages, make them in a folder named “APPNAME Help'', 
where APPNAME is the actual name of your application. 
Something that bit me was that all of our applications 
used the name “Help” for ibe Help directory, and dais 
ended up confusing Flelp Viewer. 
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2, Indicate the start page 

Once you have your HTML in a folder^ you need to 
add the following META TAG to the <HEAD> area of the 
html page that you wish to he shown first; 

<META SAME="AppleTitle*' COHTENT=‘*MyApp Online Heip"> 

Tip: you should add Description and Keywords meta 
tags if you want more info to appear in Help Viewer's 
search results. 

Gotcha: don’t leave spaces on either side of the or 
the meta tag won't parse correctly. I copied/pasted from 
Apple’s Help info site which includes extra spaces in the 
meta tag and then wondered why things didn’t work! 

3- Add the Help to your Project Builder Project 

a. Select the Resources folder in the Groups & Files 
pane on the left 

b. Choose PrQject->Add Files.,. 

c. Navigate to your Help files and select the root folder 

d. A new sheet comes dowm; select "Create Folder 
References for any added folders", click Add 

This means the Help is added as an opaque blob - 
whatever is in that folder gets copied to the app 

e. Project -> Show Info 

f. From "Localization and Platforms” popup, select 
“Make Localized” 

This will copy your help into your Project's 
English-Iproj, if that is your development language. 

4* Add the Key-Value pairs to alert the system that 
Help is available 

There are two important keys for Help Viewer to 
work: a localized one (CFBundleHelpBookName) and a 
global one (CFBundleHelpBookFolder). The global key 
indicates the name of the Help folder, and the localized 
key indicates die tide of the Help Book as it should 
appear in Help Viewer. The global key is added to the 
project by selecting die target, and in the "Applications 
Settings" tab of theTarget pane, choose "Expert". Click 
"New Sibling", and type CFBundleHeipBookFoider in 
the field on the left. Leave "String" selected as the type 
and enter the name of the folder containing Help in the 
field on the right. 



YDL 2.0 for PowerPC 


www.yellowdogIinux.coin 

by Terra Soft Solutions, Inc. 


Ai'kii. 2001 • Mac^Tech 









^ ® Tairaet; PtwwTciWeb (Atsplkationi t 

^ _J * l^iHd Phastt 1 Bajit d Sei^nqi y ^E^goalgSittings t 




pTDpeny list 


yaiw __ 

C Ffiun<fleO«yi!9opmt ntRe^kcm 

Slftiw 

$ EngtKh 

P C FSuMHeDocufmniTviKS 

Array 

T I oriiered ol^iccts 

CFSiurtdleEMCcyUble 


T Ph&loToWeb 

CF8uiKn«GetlnfoStr<ng 

String 

w Ston# Design's PbowToWeb 


CFfiurKri«lcoi(inie 

Striivg 

w PhoioTaWeb 


You add giobai keys via Application Settings 


Localized keys (keys meant to be in the language of the 
end user) are added to a file named InfoPlist.strings. Create 
this file and add it to your project, localized, if it doesn’t yet 
exist. This file typically contains strings like the get info 
string, Add the CFBundleHelpBookName and the title you 
want to he shown on the right hand side. This name MLIS'F 
MATCH the CONTENT field of <META NAME-=”AppleTitle’' 
CONTENT=''MyApp Online Help”> that you added to the 
start html page in step 2. 

[ 

CFBundlEGetlnfaString “ "StonE Design's PhotoToWeb®, Copyright 
© 1990-2001, Stone Design Corp, Visit ww-stone-coffi"^; 

CFBundleHelpBookName ” "PhotoToWeb Online Help”: 


5* Hook up a menu item to First Responder’s method, 
“showHelp;” 

Open your main application nib file in Interl'ace 
Builder. Double’Click the menu icon to bring up your 
app’s main menu. Check to see that Help -> AFPNAME 
Help is connected to the First Responder icon, and that 
the action '*showHelp:” is selected. 
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- 
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Connect the He/p menn item to First Reponder's 
showHeip: action 


6. Build the Idx index file which gives Help Viewer the 
Sherlock searching capabilities 

So far, easy, riglit' 'Hiis is tlie last step, but it has a number 
of substeps to it! At tire time OS X sliipped, there was only a 
Mac OS 9-based Carlx>n tool to make tliese indices: Apple 
Help Indexing Toof (on most of the dev CDs, eg: 

V Vo I u rne s/De v e lope r Too I s/Ciirbon L i b 

SDK/CarboiiLib_l .2J_SDK/Carbon Help Viewer/Appk Help 

Indexing TooF), 

a. Build your application with the Help directoiy so that 
Help is in its “final” relative location 

(In a Cocoa app, that's 

APPNAME.app/Contents/Resources/Englishdproj/APP 
NAME Help) 

b. In Finder, select your built application 

c. Hold down the Control key so that the context menu 
pops up 

d. Select '\Show Package Contents” to allow peering into 
your application 

e. traverse into your application package until you 
select the HELP folder 

fi Set the creator and type of all HTML files to creator; 
dibwC type: TEXT^ 

A current gotcha of tlie indexer tcx>l is that all of the html 
needs to have its creator and type set. Apple provides a 
command line tool to do tliis: /Developer/rools/SetFile. For 
example, a way to set all die html in a folder correctly would 
be to typc^ in a terminal: 

cd <HELP FOLDER) 
foreach i { *html ) 

This gives you back a prompt: 
foreach -> 

Type: 

foreach ) /Developer7Toqls/SetFile -c *hbwr" -t 
'TEXT' $i 
foreach -> end 

The foreach command lets you create commands 
that get executed on each valid file, in this case, all files 
ending in html in the current directory, 

g. Drop the folder onto the icon of Apple Help Indexing 
Tool to launch Classic and the indexing tool 
li. [f the Hie parses correctly, you'll see 0 warnings and 
0 errors, and the APPNAME Help idx file will appear 
at the top level of your help folder. 
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Control your 
web database 
development 
destiny, today. 

Today is the day you take control of your destiny 
as a professional application developer. 
No excuses. You're going to do it today, Period. 


Y our new destiny begins with a look at the 
development tools you're using. Are they 
open? flexible? scalable? Do you always worry that 
your tools can’t accomplish the job? If your tools 
limit your ability to deliver solutions, how can you 
realize your true potential? 


The tool to help you get the most out of your 
potential is 4th Dimension. The 4th Dimension 
(4D) product line is a carefully integrated, yet 
open development environment that offers unprece¬ 
dented flexibility and scalability. With the release 
of 4D version 6.7 there's never a need to worry 
about the ability to accomplish the job at hand. 
4D supports a massive range of solutions including 
web access, SSL, XML, WAP, FTP, Email and more. 
When your client asks for 
connectivity to other RDBMS 
systems like ORACLE™ or 


www.4D.com/destiny 

1.800.881.3466 opt 3 



MS SQL Server™ you simply won’t have to worry 
- 4D has been providing connectivity for over a 
decade. What if you could offer that same client 
security for the data in the database in the event 
the database was stolen? With 4D Version 6.7 
we've pioneered the use of SSL-based technology 
to shore-up and encrypt the data in the database. 
Yet there's so much more. 

Are you ready to take control, to deliver versatile 
solutions that meet or exceed your client expecta¬ 
tions? You can take that first step by downloading 
the demo of 4D Version 6.7. The demo includes a 
tutorial that quickly immerses you in 4D and targets 
you in the right direction. 

Here's to your new destiny using 4D. 

4th Dimension v6.7 

RAD • RDBMS • CCt • HTTP • SSL 


e 2000. 4D, Inc. All Rigbti Rwerffld. 4D and VfebSIAR are irodwoib of 4D SA Bmiidi and product r«fvren<»d herean on llw Irademafki or regiitefixJ trademorb of rtmir r«$pacftv» hddnr*. 
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You rntist create the iri^iex 'in situ*'so that the links anil uxfrk 


i. Copy the idx file inio your Development source 
directory's English.Iproj/APPNAME Help ftjkler. If you 
forget this step, then Help Viewer won't work! 

7. Build your application tor deployment and test help— 
Help should “just work.” Help Viewer should launch and 
display your start page. You should l>e able to make queries 
and get back clickable links to the relevant help pages. 

If it doesn’t work you should check on the following 
points of minutiae: 


• Did the indexer parse your file correctly? If not, check 
for unmatched tags. 

• Did tile Key-Value pairs get added correctly? You can open 

Info.plist inside the application Contents folder and see if 
the global key CFBundleHeipBcKikFolder is there, and that 
it exactly matches the name of the folder containing your 
help files (I recommend APPNAME Help). Does the 
English.Iproj/InfoPHst^strings file contain 

CFBundieHelpBookName key value pair? 

• Is the CFBundieHelpBookName value tlie same as your NIETA 
TAG Ibr “Apple Title” from step 2 above? 

Now, all you have to do is repeal for each language your 
prognaii supports! Vlien you do localize your application to utlier | 
hinguages, Ix^sides just translating ilie .strings and .nib files, 
rememtxjr to liave the IFTML tniasiated and llien build a new index 
for each language supported, 

CoNairsiON 

Developers hope to create intuitive and easy to use 
interfaces, but users tend to get lost more easily than we expect. 

In order to avoid tedious tech suppon aills, it is ideal to provide 
several levels of Hel[) in your Mac OS X application. Leveraging 
on Apple's built in Help Viewer technr^logy, you can provide 
deep searchable help using .standard HTML and even include 
quicktime video.s, sounds, and images, Hj 
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POWERPLAMT 

WORKSHOP 


By Aaron Moyitgomery 


First Steps 


How one goes about writing a 
PowerPlant application 

My Intended Audience 

This series of articles is intended to be an 
introduction into the use of the PowerPlant application 
framework. It is intended to be a gentler introduction 
than The PowerPlant Book supplied on the Code Warrior 
CD and more elementary than previous MacTech articles 
(in particular, those by John C, Daub). We will start by 
building a very basic application in this article and we 
will add features to it in later articles (upcoming articles 
are planned on the topics of: debugging, windows, files, 
dialogs, preferences, and panes). 

Pow'erPlant is big and it would be hard fif not 
impossible) to try to provide a simple linear introduction 
to the topic. As a result, these articles are likely to 
introduce some aspect of the framework without fully 
explaining how it w^orks. In some cases, the series will 
make a concerted effort to return to the topic bur in 
other cases the reader wnll be expected to do a Little 
reading on their own. One consequence of this is that it 
will probably be worthwhile to re-read earlier articles 
after finishing with the later articles. Another 
consequence is that often I will introduce a term without 
explanation and you may need to read more of the 
article before it makes sense. 

While writing this article, I've assumed that the 
readers are familiar with the C++ programming language 
and basic Macintosh API programming topics. In 
addition to these programming skills, readers are also 
assumed to be familiar with the Code Warrior IDE 
(including the use of the class browser and debugger). 


Myself 

Before you start reading this article, it is best to know 
where 1 learned what 1 know. I program as a hobby (not 
as a profession) and have been using PowerPlant in my 
projects for the past three years. Aldiough I consider 
myself fairly adept with the framework, I don't claim to 
know^ all the details. 1 encourage those w'ho know the 
framework better to contact me if I make any errors or 
miss any topics. Probably the best forum for this is the 
PowerPlant newsgroup and I will also post errata at my 
web site (see by-line). 

Why Learn PowerPlant 

Pow^erPlant is an application framework. You can 
find a detailed discussion of what this means in The 
PowerPlant Book, but basically, this means that it 
provides much of the routine code needed for a 
Macintosh application (in particular, the interface) and 
allows you to focus on the details of your specific 
program. At the time that 1 am writing this, a natural 
question arises: why bother with PowerPlant when you 
could use Cocoa? Personally, I decided to continue to use 
Pow'erPlant for two reasons. The first of which is my own 
personal familiarity with C++. Since I only program as a 
hobby, I donT have the time (or the need) to build that 
level of familiarity with Objective C and would like to 
continue to use a language I knowc A second reason is 
that many of the programs I write for educational 
purposes will be used in environments where OS X is not 
going to be available for a number of years. PowerPlant 
allows me to use a single code-base to support a wide 
variety of platforms (from 68K to G4). 


Aaron leaches Ui the Mathematics Department at Central Washington University in EJlensbuig, WA. Outside of his job, he spends time riding his 
mountain Ixke, watching movies and entertaining his wife and two sons. You can email him at montgoaa@cwu.edu, try to catch his attention in the 
newsgroup comp.sys.mac.oop.powerplant or visit his web site at mac69108.niath.cwai.edu:8080/. 
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The Tools 

This article will assume that you are using 
CodeWarrior 6 with the net-update to IDE 4.1.0.3 and no 
other modifications. In particular, it assumes the use of 
Universal Headers 3-3-2 and no modified FowerPlant 
files. I believe much of the code 1 write should also run 
on CodeWarrior 5 or with newer Universal Headers 
without much trouble (other than that caused by the 
Metrowerks’ PowerFlant source). If you are trying to use 
these articles as a guide and run into trouble with a 
panicular configuration, let me know and I will tr^^ to 
suggest a solution. 

Stationary Options 

The first thing to do with any project is to create a 
new project file from the Metrowerk.s supplied 
stationary. There are four opticins; Basic, Appearance, 
Document or Advanced. The Basic option is the simplest 
and all other options are built on top of it. The 
Documem and Appearance options have identical library 
.source file and include everything in the Basic option as 
well as the Appearance Classes, the Graphic Utilities, the 
Grayscale Classes and the Page ControHer. The 
difference betw^een rhe two versions is that the sample 
code for the Document option is set up for a basic 
application supporting the use of documents. The 


Felt Tip 

Sound Studio 

Record and Edit Audio 

with a sound editor designed for the Mac. 

Sound Studio will allow you to make quick edits with an 
interface as easy as a text editor. Add polish to recordings 
with fades, normalization, and edits. Create your own mixes. 
Transform them with effects. 

Sound Studio features 

• up to 16 hits, 2 channels, and 65 kHz 

• up to 2 GB of audio 

■ AIFF, Snund Designer 2, WAVE, 

System 7 Saucid, and QuickTime impart 

• edit with sample accuracy 
" fade, amplify, normalise, and invert 

■ delay, echa, reverse, and swap channels 

• smootl) and emphasize 

• resample and pitch shift 

• snap to KOTO crossings, snap to grid 

$35 

Sound Studio 

download free 14-day trial 
or order online at 

www.felttip.com 


Felt Tip Software, S07 Keely Place, Philadelphia PA 19128-2326. USA 


Advanced oplion contains everything in the Document 
and Appearance options as well as the Context Menu, 
the Debugging Classes, the Table Classes and the 
Threads Classes. This is the option I choose most 
frequently (the Debugging Classes are so good, they will 
be the topic of the second article in this series). 

For this project, I started with the Advanced option, 
moved some unused cla.sses out of the regular targets to 
a side-target (Other Stuff). We’ll add them back to the 
build targets when I start using them in later projects. I 
have also made some stylistic changes (e,g*, requiring 
explicit use of the PowerFlant namespace and adding a 
separate file to contain mainO), Finally, 1 removed some 
code so that I will be able to focus on the basics. Much 
of the removed code will reappear in later articles. 

Naming Conventions 

Before examining any .source code, the PowerFlant 
naming conventions deserve mention. All PowerFlant 
types defined by typedef macros end with a T, All 
PowerFlant classes begin with L (for library), U (for 
utility) or St (for stack-based). Class methods begin with 
uppercase letters and use capitalization as a word-break. 
Class data (static data) begins with the letter s and object 
data begins with the letter m. Calls to the Macintosh AFl 
are indicated by a global scope operator (::). Local 
variables are indicated by the prefix the. You can find 
more conventions in The Pow'erPlant Book. 

User classes (those that you write) will typically start 
with a C (for class), I also use Lit (for utility) and Au (for 
automatic, i.e., stack-based) classes. Class data for my 
classes begins with our and deject data begins with my. 
This helps me distinguish between data I am responsible 
for and data coming from tlie framework. 

Browsing the Initiaozation Code 

The first code we wall discuss is the function maioO in 
main.cp. One effective w^ay to learn about PowerFlant is to 
use the class browser to examine a function’s definition 
and commentary. In order to folkw along, you will need 
to make the project w ith the class browser activated (see 
the Build Extras preference panel for the target). 1 will be 
using the PPC Debug target although you may want to use 
a different target depending on your setup. (1 have 
removed all comments for listing in the magazine.) 

mainQ in main.cp 

int maint) 

[ 

tnitializeHeap{5 )i 
UQDGlahals;:rnltializeTQolbox{)J 
::FlushEvents(everyEvent. all)1 
UEnvironment::InitEnvironment ()i 

CBocuinentApp theApp; 
tbeApp.Runf]: 

return 0; 
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Well quickly run through the initialization code in 
niainO using the browser Selecting the InitializeHeapC) 
(e.g., by double-clicking the word) and then using Find 
Definition in the Search (or by using command-’), we 
can get the source for the function. PowerPlant 
commentary is good and the comments before the 
definition of InitializeHeapC) describe its purpose: it 
expands the heap and calls the appropriate version of 
MoreMastersO. The next method is InidalizeToolboxO 
and looking at its definition (and code commentary) you 
can see that it contains the standard Macintosh Toolbox 
initialization code. Following the toolbox initialization is 
a . :FlushEvents() call. This isn’t called in the 
InidalizeToolboxO method, but commentary in the 
PowerPlant stationary indicates that failure to call it may 
lead to problems and so we place it here. The last call 
in this sequence is InitEnvironmentO. Looking at its 
definition (and code commentary) indicates that it will 
check for things like the existence of the Appearance 
Manager Even if you do not use the UEnvironment class 
yourself, PowerPlant uses ii and so you need to insure 
that it is inidalized. 

We have now reached the class CDocumentApp. 
This class represents the Macintosh application and the 
object theApp represents this instantiation oi' the 
Macintosh application. Again, we can use the iirowser to 
examine the constructor 


CDocLinientAppO in <:DociifncnL\pp.cp 

CDociimentApp: .-CDocunientAppO 
1 

if [UEnvironment::HasFeature(env^HasAppearance)) 

( 

:iRegisterAppearanceClient[): 

) 

CTextDociJinent: j RegistarClaases [); 

1 

The HasFeatureO detcniiines if tlie Appcamnce Managcj- 
is insmlled. If it is installed, tlie application reglslens itself with 
the operating system, dlie second sttitement is a call to tlie static 
method RegisterClassesO of CTextDcxJument. Tim is necessaiy 
to build the window staicture from bie resource file and w ii] lie 
discussed in the third article. 

Stepping TtaiouGH RunQ 

The browser is gocxl if the code is very lineai; once the 
ccxle Ix^comes complicated, stepping through the source with 
the debugger can \ie a great aid in understanding. In order to 
do tills, add a breakpoint on the line CDocApplication.RunO 
call in main.cp and mn the application (wMi tlie debugger 
enabled). When the debugger lialts at tliis breakpoint, step kilo 
the RtmO method. I will describe, lint wont list, the ccxle from 
the PowerPlant source, llie first tiling that cxcurs is a sequence 
of initializations for the application: creating a menu bar, settuig 
up the AppleEvent handlers and then calling InitializeO. This 
viiTual metlicxJ should handle initialization routines tliat need to 


liappen alter tlie menu bar and AppleEvent liandlers liave been 
initialized (and hence cannot occur in the consimctor). Later we 
will use tills method to create a dynamic menu, for now we fall 
back on die kiiierited method. PowerPlant then calls 
ForceTaigetSwitchO (described below), Initializes the cursor, 
updates the menu and starts handling events. 

Event Processing 

We Iiave now readied die main event IcKip. Tliere are two 
types of events to which die application needs to respond: 
AppleE vents and menu-commands. The PowerPlant 
framework liandles die dispatching of some basic AppleE vents 
to viitual niedic}ds in the LApplic^tion class. The only ones we 
need to implement here are tlie methods associated with Open 
Application and Reopen Application events. PowerPlant 
dispatches these to the StartUpO and ReopenAppO methcxis 
respectively. 

StartUpC) and ReopenAppO in CIXxruracntApp.cp 

void 

CDocumentApp::StartUp{] 

[ 

ObeyCoiiimand(ciidJJew, nil): 

! 

void 

CDocmnentApp::DoReapenApp() 

< 

if {(UDesktop::FetcbTopRegular() ^ nil) 

(UDesktop: tFetchTopModalO = nil]) 

1 

Ob eyCommand (emdj^ew. nil]; 

1 

I 

Hie basic idea of bodi mediods Is the same: pass die 
responsibility to OheyC'onimancK). There only difference Is diat 
in ReopenAppO, the ObeyCommandO is only called if no other 
windows are open. In the acmal source file, there is a long 
tximmentaiy^ about why this is the appropriate ]iehavior 

The methfxl OlieyConimandO is a virtual methexi of the 
LCommander class (from whidi LApplicadon inherits). F.ach 
LComm^indei- h;is a supercommander (well, not quite, die top 
commander will nor have a superconimander). 'Ibe collection 
of corniTiandei's generated by tbilowing sufxrcommanders up 
to the top commander is c'alled die command cliain. At any 
given time, ex^ialy one LCommander object tias control of the 
application, diis object Ls said to be on duty. Hie call to 
ForceTaigetSwitchO that we saw alxive placcxl die application 
objea on duty. Wlien C)beylk>mni:ind() is culled, die object on 
duty should eidier oiiey die commancl or pass it to iLs base 
class. A basic example of this in this application is the 
cmcLNew^ wiien no windows are open. To see how^ this is 
handled, place a breakpoint at die top of the ObeyCommandO 
method in LDcx*:Application (you can find tliis by typing 
command”’ w^hen no text is selected and typing 
Olx^yCommiind). Once the breakpoint is set, switch to die 
application (or start it from die debugger) and select 0|x^n from 
the File menu. You should step into the 
SendAECreateDocumentO and MakeNewDrxrumentO methods, 
the second is supplied by the CDocumentApp class. 
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MsikeNewDocitmentC) in CDotumentApp.cp 

LModelObject^ 

CDocuinentApp; tMakeNewDocument {) 

E 

return new CTextDocument(this): 

1 

That was simple^ just pass all the wank off to the 
CTextDocument class, We wall leave CDocumentApp for a 
moment and explore the CTextDocument class, 

CTtxiDocumetnO tVtjm CTciitDocumcin.cp 

CTextDociiirient:: CTextDocument [ 

LComraa nder* inSuper) 

: LSlngleDoc[inSuper) 

I 

mWindow = LWindow::CreateWindow[PPob,TextWindow, this }; 
myTextView = 

static_c a sz CLTextEditView^ >( 

iDUiiidow->FindPaneByrD( kTextViev)); 
mWindow- > SetLatentSub(myTextView); 

NameNewDac 0 \ 

inWindow->Show (): 

] 

Much of tile ccxie in the constmctor handles the user 
interface and will loe discussed in greater detail in the tliird 
anicle. We iVxus on thcxse calls that concern the coniinand 
chain. The CreateWindowO method creates a LWindow^ from 


data in tJie resource fork of the application. LWindow^ is derived 
from LCooiniander and the second argument in the 
CreateWindowC) method sets die w^indow object's 
supercommander. The w'indow resource contains a 
LTextEditView and LTextEclitView also inherits from 
LCommander and its supercomimnder will Lie set to tlie 
LWindow being created. Tlie next two lines Imd the 
ElextEdiiView and then establish it as being die on duty when 
the w'indow opens. The remaining two calls are mundane: 
NameNewDoef) uses a very naive metliod to generate unique 
window' names (whicii will he improved in die third article) 
and Show{ ) makes the w^indew visible* 

Now that we have a non-triviaJ command chain, we can 
demonstrate what happens when an object cannot obey a 
command. In diis case, the command works it w^ay up to the 
ObeyCommandO implementation in LCommander and you 
should place a breakiioint in that method. Now' make sure a 
window is open in die afipEcation and select die Close item 
from die File menu. 'Fhe first time you stop in LCommander's 
Ol^eyCommaridO, a ElextEditView has receivtxl the command 
and is passing it Lipward to its SLi|X5rconimander. Running die 
debugger will cause die window to ckxse and die application 
to continue. Tlds means dial die LWindow^ object was able to 
handle die command. 

A good question aiises here; If the LWindow' handled die 
close event, what happened to the CTextDfXument? To 
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determine this, pkce a break point in the CTextEtociunent 
destaictor and close anodier window. Before looking at tlie 
destructor code, examine the stack. By selecting on various 
locations of the stack you can see that the LDocument object's 
CloseO metlrod is called wliich causes die CTextDocurnent 
objea to be destaiaed. 

^CTextDocumentO in CTcsctDocimient cp 

CTextDocument:; -^TextDocument() 

try 

S 

TakeOffDutyt): 

J 

catch (...) 

{ 

J 

f 

The destructor is very simple and only calls TakeOffDutyO 
which is inlierited from LCommander. 'rhis call takes the 
CTextDocaiment off duty (a good diing since its memory is 
about to be reclaimed ). 

To see a more complicated demonstration of the 
command chain, make sure a lireakpoint Is still set in 
LCommander’s implementation of OI 1 C 7 Commando. Now 
make sure a window^ is open and chose Quit from the File 
menu. Tills command will need to work up many levels in 
the command chain. The LTextEditView object passes ii to 
the LWindow object which passes it to the LDocument object 
which passes it on to the lApplication object which causes 
the application to quit. 

Menu Manipltlation 

Tlie other virtual medic xl diat you will need to override 
when you add (or remove) commands is 
FindCommandStatus(). We will discuss dus more liilly in a later 
article w^hen we handle menu management, hut for now^ we 


only need to worry about the first two parameters. Tlie fiist, 
inCommand, Is c)f type ComniandT and is die coinniand wliose 
status is lieing determined. The second, outEnabied, is of type 
Boolean<& and will be set to tme if the LCommander object can 
handle the command. Each time the menus are displayed, the 
method FindCommanclStatusO is called in a manner analogous 
to OlieyCommandO^ If any LCommander in the command 
chain can liandle the command, the method returns true and 
the menu item is enabled. If no LCommander in die command 
chain can liandle the command, the method will return false 
and die menu item will lie disalited. Because they are called in 
identical ways, OlieyCommandO and FindCommandStatusO 
need to he consistent in each ckiss. 


FindCommandStatusO in CDocumeniApp.cp 

void 

CDDcmnentApp:: FindCoiimandStatus { 

CommandT inCommand, 

Booleanfii ontEnabled, 

Boolean^ outlTsesMark, 
tflntl6& outMark, 

Str255 outName) 

I 

switch (inCotnmand} 

[ 

case cmd_0pen; 

! 

DutEnabled = false; 

I 

break; 

default: 

I 

LDocApplication::FindConnnandStatus( 

InConirnand, oUtEnabled, outUsesMark, 
outMark. outName); 

1 

break; 


Tlie Powerldant class l.DocApplication assumes the 
application will liave the ability to o(ien ckKumenLs. Since we 



SUPERIOR 


Xcaret Pro Expansion Bay CDRW Drives 



* Bootablef • Hoi Si/vappabie • Fast Backup or Ff/e 

• Toast™ 4 Software * Protective MCE Carrying Case 
•Avatlabie for PowerBook G3 98 (Waii Street) or 

PowerBook G3 99 & 2000 (Lombarti & Pismo) 

ETuneg and Disc BtirngrBHBit 


Internal Hard Drive Upgrades for PowerBooks 

• Tbe BEST iniemai Hard Drive Upgrade Kits for your PowerBook! 

• Package inciudes bard drives from tbe same manufacturers that 
shipped in tbe PowerBook from Uk factoryt bundied with 
everything you need for a successfui instaiiaUon 

• Higb-Speed 10GB, 20GB, and 30GB Capacities 

DataShuttte Xtreme Portabie Hard Drive 

■ Tbe Most VERSATILI Portabie Hard Drives Anywhere 

• FireWire Hard Drives with Flexibie USB and PC Card Options 

• Higb-Spe^ tOGB, 20GB, and 30GB Capaciti^ 

• Mso available, tbe Do-tt-YburseifUataShut^ Xtreme Kit - 
Convert Your old internal Drive into a Portable External Drive! 




'"tl'rV POWERBOOK 

Great 

Xcaret Pro Expansion Bay Hard Drives 

rating 

• Ultra Fast! • Hot Swappabie •Bootabie 

• Compact * Protective MCE Carrying Case 

• Higb-^Spi^ fOGB, 20GB, and 30GB Capacities 
•A/sa avaiiabie, tbe Xcaret Pro Expansion Bay Kit - 

Convert Your old Drive Mo an Expansion Bay Dnve! 

•Avaiiabie tor POwerBook G3 98 or PowerBook G3 993 2000 



USB FlexLight 


'7itu m in a te Yo m Workspace 



• Convenientiy lights up your keyboard and surrounding 
paperwork. • Twists and Bends so You can Direct tbe 
Ugbt Where You Want it • Powered by tbe USB Port 

• Comes with Both a Ciear and a Red Diffuser - You Choose the 
Type of Ugbt to Suit Ydur Situation • Very low Power Draw 



Mat Cofliponenrs iigineerd 



Distributsd by: 


For more info: 

WWW . mcetech .com 

800.500,0622 

949,458,0880 

Contact us for a dealer near you. 

















I’d rather create clocks than Invoices. 

If I wanted to keep books all day, Vd have been an accountant. 



MYOB software is the simplest, most powerful, most complete solution 
for managing my company on the Mac, from the day to day to the 
bottom line. 

Antique frames. Quartz movements. That*s my business. 

IdYOB software works for me 









Win a free ilVIacI 

Simply log on to; 

WWW. powe rmax. com/macteclt. html 
and register to win an IMac! It’s that simple. 



great source for OS X! Great buys on Apple 
‘S?”" refurbished product! 


PowerMax is a 

> Aqia DElr intarface * Gi’i 

* X[fbjr sraplil^ 

OS X Survival Buftdles: huge iuternal I Hew price on 
hard drives and extra RAMI ^ 

Package 1: ^ 

* jrrternal 75 Sb IBM DeskStar 
7200 rpm drive w/5 yr warranty VMQ 

• 256 Mb Additional MB RAM* IJ5TJ 

• OS X Software 

Package 2: 

• Internal 45 Gb IBM DeskStar a 

7200 rpm drive w/5 yr warranty § 

*128 Mb Additional MB RAM" ^ 

* OS X Software )at&-model CPU^ 


Best price ever 
Qit a Cube! 

$1095 


Graphite IBoor 
G3/466 64/IQ/DVD 

$1488 

^ G4/500W/256 

■ RAM,27GhHD 
I* ■ DVD-ROM, Zip 

$2145 

F(KtD<Y& Reseller Reftirblslied ttoc"" 

iMoc' 3506 V^/ 74 xO) . . . 5649 

400 64/10/DVD.. ...$708 

InSotfttoc™ 400 64/10/CD . m 

64^50 44/10/a)/56k. .....51049 

G4/40044/I0/C0/S6k ..$1088 

Gfophils iBook'J6664747CD-..S1 169 

Cute 04/450 44/?D/DVfS,.. ,..$1099 

PowerBook^ 75032/4/(0. .$1329 

G4/4SO128/2O/i0/Zip. .$1499 

Graphite IBook” 64/1 Q/DVD„. ,$1499 

Ptjwflr&oflk® 4D044/6/DVD„..,.S17SB 
G4/5EK)256/27/tM)>^ .$2149 


Cube & display w/extra RAM 

Ref. G4/450 Cube upgraded to -- 'M 

128 mb RAM. 20 Gb drive, DVD- I . 

ROM drive and a 17' Apple Studio 

display." Esdend your warranty to ft'f E^l- 

three years for only S249. 


Beige 63/266 Tower w/display 

Get this rock-solid pre-owned k.. 

G3/266 Tower complete with 128 [ W1 [ 

mb RAM, E Gb hard drive, internal 
Zip drive and beautiful Apple 1710 
Trinitron for one great price! 


iMac” w/extra RAM & printer 

Ret Indigo 400 iMac™ DV w/ 128 mb.^^^\ 
RAM, 10 Gb drive, CD-ROM and a 
Canon BJC-210D printer. Extend your 
warranty to 3 years for only $149. MTjTjui 
Price after Canon mfgr. rebate. 


G4/500DP254/40/( 
AndQWi^ me 

fldilylhedWws.. 

6100 sews... 

72OOs0iw5.. 

PowerBose DeskTops ...„ 
PtiwfflCentef fto Towefs. 


64 & 17" display w/extra RAM 

Mew G4/400 Tower upgraded to 
128 mb RAM. 20 Gb drive^ DVD- ' 

ROM and a 17* ref. Apple Studio 
display. Extend your warranty to t K.f 

three years for only $249. 


FireWire 45 Gb drive ref .$246 

IFireWlre 75 8b drive ref.. .$446 

FireWire CD-RW 16x18x4Qx... $346 
Eleelree22blee II Display rel... $946 
Over 100 alfier lacie items o n sal el 

fjf/t- / W^'ll fske your Mac OS^ 
|£U computer in trade toiverd 
_ the purchase of new 

with 

lor yi details! 


G4 Gmphiie Towets 


7500 series.... 

......4249 

76(10 wflK.. 

$779 

7300 series.. 

..$299 

SSro series....... 

.$339 

Umo»S9001owera...... 

..$389 

f^Book*^5300Cs^........ 

.$459 

9500seiie!i..„...... 

. $480 

8600 saws....... 

...$499 

9600 sates...... 

,,.,..$699 

WBbe.. 

. 4569 

irttor 63/266“ vfflfews coion... 

..$599 

iiWee’ G3/333- vniiais 

B«ge G3 Desktops 

$629 

5599 

Ge^ G3 Icftfers .. 

$679 

PoweiBooic^' 14Q0C series. _ 

$699 

PowefBodk'® G3's.... 

.$9S9 

Glue S White G3 TowefS. 

......$949 

..... 

..$979 


800 - 689-8198 

www.powemiax.com 

Local: (508) 6Z4-18Z7 • Fax (503) 6Z4'1635 
email: sales@powermax.com 

• PenuHlnmnng • l«l m .Anmils • BaiiiiiaaUmsing itaatjiicttochiiiigewitai 

•IMyS 8 £CiBblllSfl'WGb^ noUcePnoesEefiectcastid^- 

cffljnL Credit (ard orders sti^ 
ysriHedapi^lrauduientuBe. 
With usee# credit card as ppmt 
DUEtomer adratedges that some 
prodiids are ^ject to finals^. 
Mar^fprioesarelifTiitedlDstoiic^ 
land. All bi^ or product names 
am fegfeiieredtradmarfcs ot Uieir 
respectwe holders. 


NASH 



Knowledge is Power 



aren’t going to implement tinis until we disaiss files (in the 
fourth aitLcle), we need to disable tlie command in the File 
menu. We simply set oiitEnabled to indicate tliat die command 
is never tiandled and the item wDl remain disabled. Similarly, 
the CTextDocument overrides its FindCommandStatusO 
method to disable tlie cmd_Save, cmd_Save.As and cmd_Print 
comniimds. You can trace this method in exaedy the same way 
as we did for ObeyCommandO, but diat will be left as an 
exercise for die reader. 

Concluding Remarks 

If you’ve followed along so far^ you should be able to 
start examining some of the command chains in the sample | 
projects dial are provided on the CodeWarrior CD. You I 
might also want to start reading dirough the references I 
present at the end of this aiticle. The next article wall discuss 
PowerPlant’.s debugging classes. Following that we will 
expand on PowerPlant's document classes (windows in the 
third article and files in the fourth article). 

PowerPiant References 

The PowerPiant Bexjk on die CodeWarrior CD is an 
introduction to PowerPiant provided by Metrowerks. Unlike 
tills series of articles, Tlie PowerPiant BcK)k ftmises on tiie 
interface building as[aects of PowerPiant First. If you need to 
obtain a high level of proficiency with Pow erPiant, diLs Ls the 
b<x>k to work from cover to cover. The Pow^erPlant Advanced 
Topics bcxik on the CcxIeWairior CD continues where The 
PowerPiant Book leaves off. It coven: more complicated classes 
such as the Dmg ik Drop Classes, Tluead Classes and 
Networking Classes to name a tew. Tlie topics are presented so 
diat you will Ix" able to read each ckipter as you need it (and 
not necessarily in a sequential order). Togetlier these txxiks 
constitute die yirimaiy texts for learning PowerPiant. 

Tlie PowerPiant Reference on die CodeWarrior CD 
provides documentation for most of die PowerPiant classes. I 
Ibund diis useful for a short period of time wMe learning 
PowerPiant, hut after a few’ iiiondis 1 began to rely more on tiie 
class browser, the aeiual soLirce, and the commentary’ in die 
source instead of the reference lxx)k. 

If you have access to old MacTech articles, the “From die 
Factory Floor” articles in the October, November and December 
1998 issues discuss PowerPiant. The first two of these .start with 
a “How^ would you learn l^ow^erPlant” question. John C. Daub 
also wTote a series of MacTech articles from December 1998 
through June 1999 which cover individual components of 
Pow'erPlant (but do not cover the basic classes), The MacTech 
issues from 1999 are available online, but the 1998 articles were 
not up when 1 checked. You will want to search the article 
archives at <http://www, mactech.com/>. 

Finally you might lx able to find a Pow^erPkint class at 
Metrowerk’s CtxleWirrior U site <http://wvwv.coclewarrior.com/>. 
Tliese courses tend to follow' Tiie PowerPiant Book. K1 
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of neorly limitless potential, www.eseMerote.net 6S6li6rQt6 
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Darwin: Mac OS X’s Core OS 


B eneath Mac OS X's user-friendly and attractive user interface, 
Aqua, and the application frameworks (Classic, Carbon and 
Cocoa) IS Dara^in: Mac OS X’s core OS. Unseen by users, 
Darwin provides a strong yet flexible foundation with features like 
preemptive multitasking, protected memory and real-time support 
that make Mac OS X a truly modern operating system. 

The focus of this article is to provide a brief overview of 
Darwin and iLs components as well as give an introduction to 
developing kernel extensions—modules that extend Darwin’s 
functionality. For more in-dcpth information, you should read 
Inside Mac OS X: Kernel Environment which is available, along 
with other documents referred to in this article, on the Apple 
Developer Connection (ADC) web site in the Mac OS X 
Documentation section: 

bttpilldeveloperMpple.comltechpubsImacosxImacosxbtml 


Most of the reference documents can be 
found in the /Developer/Documcntation/ 

Kernel directory on any Mac OS X system 
with the Mac OS X Developer Tools package 
installed. 

Components of Darwin 

Just like in the old Reese's Peanut Butter 
Cups commercials (“You’ve got chocolate in 
my peanut butter... No, you’ve got peanut butter on my 
chocolate!”), Darwin blends a mixture of mature industry^ standard 
components such as Mach and BSD with Apple^mgineered 
components to provide Mae OS X with a stable, reliable and 
extensible foundation. Danvin consists of five main components: 
Mach, I/O Kit, File System, Networking and BSD, 



ADC Programs 
and Mac OS X 

R egister today for Apple's Worldwide Developers 
Conference (WWDC) from May 21-25, 2001 in 
San Jose, California. WWDC will feature more than 
100 in-depth technical sessions and hands-on labs. 
You'll have access to Apple engineers and technology 
experts to answer your software and hardware 
development questions. 

Naturally, WWDC 2001 session topics will cover a full 
range of Apple development subjects: Mac OS X 
architecture (Darwin, Quartz, OpenGL, QuickTime, Carbon, 
Cocoa, Aqua), hardware, BSD UNIX, Java, WebObjects, 
development tools and much more. 

Register now to attend the conference, network with 
peers and learn about all of the exciting technologies 
designed in Mac OS X. Pricing, detailed session 
information and registration information is available at: 
httpJiwww,appie,comfdeveioperfwwdc20Q1/ 

Remember, ADC Select and Premier members receive 
special discounts. See you in Mayl 


Mach 

At the hean of Darwin is Mach, based on Mach 3-0 from Carnegie 
Melton University. Mach manages processor resources such as CPU 
usage and memory^ handles scheduling, provides memory 
protection and provides a messaging-centered infrastructure to the 
rest of the operating system layers. Mach provides Mac OS X with 
protected memory, preemptive multitasking, virtual memory and 
real-time support. 

I/O Kit 

Darwin provides an object-oriented framework, I/O Kit, for the 
development of device drivers. I/O Kit not only faeflitates the 
creation of drivers for Mac OS X but also provides much of the 
infrastructure that drivers require. It consists of three major 
components: families, nubs and drivers. 

A family defines a collection of software abstractions that are 
common to all devices of a particular catcgory\ Apple provides 
families for protocols such as USB, SCSI and FireWire, as well as 
for devices such as storage, HID and frame buffers. Mac OS X 
developers should rely upon these provided families—not create 
new families. 

A nub is an I/O object that represents a device or logical service. 
A nub may represent a bus, a disk, a disk partition, a keyboard or 
any number of similar entities. 

A driver is an object that manages a specific piece of hardware, 
implementing the appropriate I/O Kit abstractions for controlling 


John Signa is the Technology Manager for Mac OS X Core OS in ^pk Worldwide Developer Relations. John first got involved in the Macintosh industry in 
1988 writing software for Orange Micro*s printing products. He later spent three years at SuperMadRadius writing display and video drivers. 
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that hardware. Mac OS X provides a collection of drivers that 
handle standard devices such as hard drives and human input 
devices. If your device complies with an industry standard but has 
additional functionality, then you simply need to subclass the 
provided driver and implement just the code that handles the 
uniqueness of your device. 

Anyone working with I/O Kit—either as an appliation writer or a 
driver developer—should read Inside Mac OS X: 1/0 Kit Architecture 
to get more background on how 1/0 Kit works. Device driver 
developers should also read Mac OS X: Writing I/O Kit Drivers. 
Application developers should read Inside Mac OS X: Accessing 
Hardware from Applications. Both documents are available on the 
ADC web site in the Mac OS X Documentation section. 

File System 

The file system component of Darwin is based on an enhanced 
Virtual File System (VFS) design, which provides the ability to add 
in new file systems and enhance those already supported, including 
HFS, HFS+ UFS, and ISSO 9660, VFS stacks also aUowyou to 
create and layer new capabilities, such as file-based compression or 
enayplion onto an existing file system type. 

Networking 

Mac OS X also provides an extensible networking system. By 
implementing Network Kernel Extensions (NKlis) developers can 
add support for additional networking protocols as well as enhance 
the networking functionality already provided. Developers who 
need to extend Mac OS X's networking capabilities should read 
Inside Mac OS X: Network Kernel Extensions for more details, 

BSD 

Darwin wraps a customized version of BSD 4.4 around the kernel. 
Darwin's implementation of BSD includes many of the POSIX APIs, 
exporting them to user-space, and abstracts Darwin's file system and 
networking. Darwin’s BSD also provides Mac OS X’s process model 
basic security policies and threading support. 

For developers, the biggest advantage of Darwin's BSD 
implementation is that it enables you to quickly pon UNDC-style 
applications to Mac OS X. In some cases, developers have had their 
UNIX applications up and running on Mac OS X in a matter of 
hours. Because BSD does not provide CiUl APIs, you will need to 
aeate a Carbon or Cocoa application to handle the user interface. 
Much of this work can be done using Interface Builder, Apple’s user 
interface design tool available on the Mac OS X Developer Tools 
CD. 

Developing Kernel Extensions 

To handle enhancements to the kernel, Mac OS X provides the 


abihty to dynamically load pieces of code, referred to as Kernel 
Extensions (KEXTs), without needing to recompile the kernel. All 
kernel extensions are implemented as “bundles”—folders that the 
Finder treats as single entities. In addition to having names that end 
in “.kext,” all kernel extensions contain a property list (plist), which 
is an XML text file describing the I^XT’s contents and 
requirements. Additionally, a KEXT will usually, but not always, 
include a module (KMOD) that contains the binary code that is 
actually loaded into the kernel and run. A KEXT can also contain 
additional resources such as icons for the Finder. 

Before you dive into developing a KEXT, you must decide if you 
really need to run in the kernel space. Compared to code running 
at the user space, kernel extensions are more difficult to write and 
debug. Furthermore, bugs in kernel extensions can have far more 
severe consequences. For example, a memory access error in a user 
application can, at worst, cause that application to crash yet leave 
the rest of the OS functional. In contrast, a memory access error in 
a KEXT causes a system panic, crashing the entire operating system. 

When you are trying to decide if a piece of code should be a 
KEXT, the answer is generally no. Just because your code was a 


Continued on page 55 ^ 


Project Builder 
Tips & Tricks 

• Regular expression searches are very powerful. If 
you use regular expressions with subexpressions, you 
can reference the subexpressions in your replace 
string using “\#” syntax where “#’* is the index of the 
subexpression. For example, if you search for the 
regular expression “foo{.*)bar” and find an occurrence 
with is 'Tooabedbar,” a replace string of “barMfoo” 
will change that match into “barabedfoo.” 

• Find Options Sets can make your batch searches 
much faster. Try defining a set that does not search 
framework headers and one that only searches 
framework headers, and swap between them 
depending on what you're looking for. 

• Lots of cool features are only available if you index 
your project. You have to index a project manually, the 
first time. After that, your index will be kept up to date 
automatically. 







SAMPLECODE - Networking: IMAccessSample 
SAMPLECODE - Files: MoreEiles 
SAMPLECODE - Printing: PostScript Output Filters 
SAMPLECODE - Java: JNISampk 

SAMPLECODE - Human Interface Toolbox: CarbonCustomLisi 
SAMPLECODE - Networking: OTLookupNameTest 


The following software is available from the Download Software 

area of the ADC Member Site at: 

httpillconnectMpplexoml 

• CarbonLib 1.2.5 GM SDK 

The CarbonLib 1.2.5 SDK for Mae OS is now available to all 
developers. This SDK provides all the files needed to begin Carbon 
development. CarbonLib 1.2.5 supports Mac OS 8.6 and greater. 
bttptlldevelopevMpple. comitecbnicall 

• CarbonLib 1.3d6 SDK 

The latest prerelease version of the CarbonLib L3 SDK for Mac OS 
is now available to all ADC Members. 
httpilldeveloper.applexomltecbnicail 

Developer Documentation 

The following new and updated documentation is available to help 
you on your way to successful Mac OS X application and peripheral 
development at: 

httpzHdeveloper, appie. comltechpnbsl 

• iMac Developer Note (Update) 

• Inside Cocoa; Object-Oriented Programming and the 
Objective-C Language 

• Mac OS X: An Overview for Developers * A lO-page PDF 
document that explains the unique combination of technologies 
in Mac OS X and discusses the benefits of those technologies to 
developers. 

httpilldeveloper.applexomimacosxl 
TNI 191 - USB Software Locator 


QA1008 - WaitMouseUp documentation errata 
QAlOOl - Detecting CD/DVD media types 
QA1006 - Displaying Help 
QA1005 - Open File Limits on Mac OS X 
QA1004 - Displaying the device tree in Mac OS X 
QA1003 ' Enabling Macintosh-style Menu Bars 


SAMPLECODE * QuickTime: Importers and Exporters: 
ElectricImageComponent 

SAMPLECODE - Human Interface Ibolbox: ScroUingTextllscrPane 
SAMPLECODE - Human Interface Ibolbox: MLTEEditField 
SAMPLECODE - Human Interface Toolbox: HTMLUserPane 
SAMPLECODE - Human Interface Toolbox: HandyScrolUngSample 


Upcoming Seminars 
and Events 

For more information on Apple developer events please 
visit the developer Events page at: 
bttptHdeveloper. apple, comfei^entsi 

Training and Seminars 

Programming with Cocoa 

Taught by Aaron Hillegass at the Big Nerd Ranch, Ashville, NC 
and Atlanta, GA, Five-day classes are taught on developing 
web-based and Mac OS X applications. 
http'.llwum.bignerdrancbxQmlwben.himl 

Developer Related Conferences 

National Association of Broadcasters (NAB) Conference, 

Las Vegas, NV 
April 21-26 

Produced annually by the National Association of 
Broadcasters, NAB2001 is the worlds leading conference and 
exhibition for the converging electronic media 
communications industries. Apple will be exhibiting in Booth 
#.M913L 

http: //wwu\ nab. orglconventionsInablOOll 

Worldmde Developers Conference (WWDC) 20i)f 
San Jose, CA 
May 21-25 

Register now for Apple’s Vtbrldwide Developers Conference 
2001, which takes place in San Jose, California from May 21- 
25. ADC Premier members receive a free pass to the 
conference and AIX! Select members receive discounts for 
early registration. For schedules and other details check out: 
bttptllwww.applexomjdeveloperlwwdcIOOll 

MacHack Conference, Dearborn, MI 
June 21-23 

MacHack, in its sixteenth year, remains centered around 
cutting edge software development. MacHack’s uniqueness 
derives from the informal feel and the LIVE coding that 
occurs around-the-clock during the conference. 
bttp:i/wum machackxom/ 



New Mac OS X 
Related Releases 
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system extension in Mac OS 8 or 9, does not mean that it must 
necessarily be a kernel extension in Mac OS X. To help you decide, 
ask yourself the following questions: 

• Does your code need to take a primary interrupt? That is, does 
something in the hardware need to interrupt the CPU? 

• Does the primary^ client of your code reside inside the kernel (for 
example, a hard drive whose primary client is the file sy’stem)? 

• Do a sufficiently large number of running applications require a 
resource that your code provides (for example, a file-system 
stack)? 

If you answered “no"’ to all of the above, then you should 
consider developing your code as a library or a background 
application rather than as a kernel extension. You might also 
consider using one of the user level plug-in architectures provided 
by Mac OS X. such as QuickTime components or Printer Modules. 
However, if you ire writing device drivers or code to support a 
new volume format or networking protocol, KEXTs may be the 
only solution. 

Fortunately, while KEXTs are more difficult to write than user- 
space code, several tools and procedures are available to enhance 
the development and debugging process. Curamtly you'll need to 
use Apple’s Project Builder IDE to create KEXTs and use GDB for 
debugging. For a quick introduction on creating and debugging 
KEXTs with Project Builder GDB, you should read Inside Mac OS 
XiKemel Extensions Tutorial. 

Open Source 

In March, 1999, Apple announced the Darwin Open Source 
initiative, making Apple the first major computer company to make 
open-source development a key part of its ongoing sofiw^are 
strategy. Apple has released the source code to virtually all of the 
components of Darwdn to the developer community, providing you 
the ability to see how Apple has implemented Mac OS X's core OS. 
Not only is this helpful in undersUinding how the OS works, but it 
also allows you to utilize portions of Darwin within your own 
products. Before doing so you should review^ the Apple Public 
Source License to understand the limitations or obligations this 
entails. It can be found at: 
httpiUopensQu rce. apple, com/apsl/ 

Summary 

Developing kernel code is never trivial, however Darwin’s flexible 
architecture makes it easier than ever before to w rite drivers or add 
additional file systems for Mac OS X, By implementing such a 
flexible architecture in Darwin, Apple has provided a foundation that 
delivers the reliabiliiy' and performance you’d expect from a modern 
operating system. Moreover, releasing Darwin to the open source 
community ensures that it will continue to evolve as a high-quality^ 
interoperable system built on open standards. 


Did You Know? 

Darwin: Document It! 

ou probably know that you can go to Apple’s 
Open Source web site (www.opensource, 
apple.com) and download the binary and 
source code of Darwin and other Open Source projects. 
But did you know that you can get more than code? 

You can also obtain documentation as well. And you 
can add to this store of information. 

That's because this documentation is created by 
developers in the Apple Open Source community for 
other developers. The Darwin Documentation project 
(also at www.opensource.appie.com) provides you with 
an assortment of tools and guides to help you compose 
professionahlooklng documents. These documents are 
of three types: 

• HeaderDoc—Reference documentation produced by a 
Per! tool that parses structured commentary embedded 
in C and C+-f header files and produces rich HTML 
output from that commentary. 

• HOWTO documents—Conceptual and task™oriented 
information on specific programming topics. HOWTO 
documents are based on DocBook XML because from 
this format tools can process the document into multiple 
formats (HTML, PDF, etc.). The documentation project 
provides a template and instructions for creating 
HOWTO documents. You don’t have to learn DocBook 
XML if you don't want to; you can submit the HOWTO 
as an HTML document and Apple will convert it to XML. 

• Manpages—^Traditional UNIX-style documentation of 
command-line tools and utilities. 


“Built for Mac OS X” 

Badge Now Available 

Tell the world your product runs on Mac OS Xi The 
artwork, licensing requirements and guidelines for use of 
the new “Built for Mac OS X” badge are now available 
on the ADC Software Licensing web site. Please note 
that this badge cannot be used for products that launch 
the Classic environment. 

http://deveiopenappte.com/mkt/swl/agreements, 

htmtttmacosx 








PROGRAMMER'S 

CHALLENGE 


by Bob Boofistra, Westford, MA 


Crossword n 

Several years ago we held a Programmers Challenge based 
on crossword puzzles. So when my son came home from school 
with an idea for a crossword Challenge, my first thought was that 
we had been there and done that. The old Cliallenge required 
readers to solve a crossword puzzle, fitting the available words 
into a predefined pattern, without the benefit of clues. My son’s 
problem, to generate a crossword puzzle, Is sufficiently different 
to make a potentially intere-sting Challenge. 

The prototype for the code you should write is- 

typedef struct Words f 

char •theWord; siring 7 

short value; /* points ViUuc for the Word 7 

1 Words: 


typedef atruct WordPoBltlqnE I 

short whichWord; /* index in Words array of word being placed 7 

short row: I* row in which the first letter of the wtjnd Ls 

plaa-d 7 


short col: /* col in which the firat letter of the word is 

placed 7 

short orientation: /* tiedownV 

1 WordPosltions: 


long /' numberOfWordPositiGns '/ Crosswordll { 

short puzzleSize. t pu/Jlc ha.'i puiodcSizc rows and ctilumas V 

const Words words [] , /* words to be iLsed to form the puK/le 7 

short numWords > r number of words! 1 available 7 

WordPositions pos itions [] t placement of words in purple 7 

); 


The homework assigntneni that inspired this Challenge 
was from Chemistry class. Students w^ere required to 
generate a 20x20 crossword puzzle using the names of the 
first 103 elements from the periodic table. Each word placed 
had a value equal to the atomic number for that element. So 
placing the word “law'rencium” earns you 103 points, 
’"molybdenum” is worth only 42, but “lead” is wonh 82. The 
assignment was to generate a crossword puzzle wcmli as 
many points as possli^ie. 

For rhe Challenge, well generalize the problem to work 
with an arbitrary list of words and arhltnirily assigned 
values. The puzzle dimension will be puzzleSize x 
puzzleSize instead of 20x20. You should deckle whicli 
words to place where in the puzzle and return your word 
placements in the pt)sitions array, specifying in 
positii:)nsG.whichWord the index in words of the word being 
placed, the cell in which the first letter of the word is placed 
in positionsD.row' and positionsU.col, and the direction the 
wx>rd is being placed in positionsO^orientation. Your 
Crosswordll routine should return the number of words 
placed in the puzzle. 


A few constraints: Each of the words wall be at least 
3 letters long and terminated with a zero byte. Every pair 
of adjacent letters in the puzzle you form must be part of 
some word. No word may occur more than once in the 
puzzle. Words may be placed horizontally or vertically, 
but not diagonally. 

The winner will be the solution that earns the most 
points. Points will be based on the value of the words 
you place in your crossword puzzle, minus a penalty of 
1% for each minute of execution time. The Challenge 
prize will be divided between the overall winner and die 
best scoring entry from a contestant that has not won the 
Challenge recently. 

This will lie a native PowerPC Challenge, using the 
CixleWarrior Pro 6 environment. Soliiticms may he coded in 
C, C++, or Pascal. You may provide a .solution in Java 
instead, provided you also provide a test driver equivalent 
to the C code provided on the web for this problem. 

Three Momiis Ago Winner 

Congratulations to Willeke Rieken for winning the 
January Tetris Challenge. The Tetris Challenge required 
readers to provide a player for the classic Tetris game, 
Willeke actually won liy default, as his was the only 
entry. As IVe said before, ytju can't win if you don't play. 
With this win, Willeke vaults into second place in our 
Challenge points standings. 

Willeke describes his scilution as “low tech”. The heavy 
lifting is done in his MovePiece routine, where he 
determines the po.sition and orientation of the current 
piece that provides the best fit. His heuristic for best fit 
takes into consideration the number of unreachable empty 
.spaces created by placing a piece, with special weighting 
against placements that create “deep pits”. The solution 
does not take advantage of the of^porrunity to move a 
piece after it has been dropped, nor does it use the 
information provided about tiie next piece to be placed. 

Top Contestants 

Listed here are the Top Contestants for the 
Programmer's Challenge, including everyone who has 
accumulated 20 or more points during the past two years. 
The numbers beiow^ include points aw^arded over the 24 
most recent contests, including points earned by this 
month’s entrants. 
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Programming Doesn't Have 
To Be This Difficult. It's REALbasicI 


r REALbasic is the award-winning, visual, 

I object-oriented BASIC development 
environment for the Macintosh. 

Use REALbasic's visual interface builder and pktform^indqjendent 
language to build native, compiled—^not interpreted'—professional 
quality applications in a fraction of the time it would take in C/C++. 
Because our language is platform-independeot you only need to 
write a single set of code to create applications for both Macintosh 
and Windows. Leverage your C/C++ experience to extend 
REALbasic's capabilities using shared libraries, Mac OS Toolbox 
and Wm 32 API calls or by writing cross-platform REALbasic plug-ins- 

Create prototypes, Internet applications, database front-ends, even 
games with REALbasic! Its OOP language employs everything 


you'd expect from a modem development environment—methods, 
properties, classes, subclassing, inheritance, constmctors and 
destmctors, virtual methods, and more. The IDE supports multi¬ 
threading, extensibility, TCP/IP controls, plus multimedia and 
QuickTime tools, and support for standards such as SQL, ODBC, 
AppleScript, and XCMDs. You can even import Visual Basic forms 
and modules. 

Go to www.realbasic.com NOW to download a FREE 
trial version or call 512.263.1233. 

m REALbasic 



MacPowerOi 

Products of The 



aoOG (%JT(w-Up - Beart Macaffloan User 


*Free update for all owners of REALbasit: 2.0 and above REALbasic and the REALbasic logo are trademiarics of REAL ^oftware^ Inc Apple and the Apple logo 
are trademarks of Apple Computer, Inc < registered tn the U.S., used with permisaon All other trademarks are the property of their respeaive owners. 









Macworld 

Conference & Expo. 



Register Online Today! 

www.macworidexpo.com 

Cali Toll Free 1-800-645-EXP0 


ChfflBl BKl M4iBgKi 
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WORLll EXPO / 
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Conference Programs & Workshops 

July 17-20, 2001 


Exposition 

July 18-20, 2001 


Jacob K. Javits Convention Center 

New York City 
















Register Online by June 18, 2001 

for special sa¥ingss Refer to Priority Code: A-MTC 


In it’s se¥enteenth year, Macworld Conference & Expo 
remains the ultimate venue for all levels of Mac users. 




Macworld HlacworUcom 

llllacWEEK.com MacCent^al.(^V1n 


professionals, enthusiasts and the Mac-curious to gather 
and experience the excellence of Mac technology! 

Macworld Conference & Expo showcases the hardware, software and 
peripherals you are looking for, as well as the technologies, applications, 
techniques and solutions you may not be aware of. 

Take home the knowledge and solutions that will bring excellence 
into your world. 


Macworld Conference & Expo’s world-renowned conference programs 
offer educational and in-depth training sessions for all experience levels. 


MacBeginnings 
are high-energy, 
informative sessions 
that acquaint you with 
the Mac community. 


Macworld/Users 
continues to be one 
of the best educational 
values anywhere for the 
general practitioners. 


Macworld/Pro offers 
the most sophisticated 
training available on 
Macintosh for the 
advanced users and 
skilled professionals. 


Visit www.macworldexpo.com tor continuous event updates! 


• Visit over 400 exhibiting companies 

• Discover thousands of new products 
and services 

• Test-drive the latest 
applications 

• View live 


Participate in competitions, drawings 
and giveaways 

Expand your digitai iifestyle 


Evaluate the latest technology 





Rank 

Name 

Points 

Rank 

Name 

Points 

T 

Munter, Ernst 

281 

5. 

Boring, Randy 

52 

2. 

Rieken, Willeke 

85 

6. 

Shearer, Rob 

48 

3. 

Saxton, Tom 

76 

7. 

Taylor, Jonatlian 

36 

4. 

Maurer, Sebastian 

68 

8. 

Wihlborg, Claes 

29 


... AND THE Top Contestants Looking for a Receni' Win 

In order [o give some recognition to other participants in 
the Challenge^ we also list the high scores for contestants who 
have acciiniulated points without taking first place in a 
Challenge during the past two years. Listed here are all of those 
contestants who have accumulated 6 or more points during the 
past two years. 


Rank 

Name 1 

Points 

Rank 

Name Points 

9. 

Downs, Andrew^ 

12 

17. 

StroLit, Joe 

10 

10. 

Jones, Dennis 

12 

18. 

Hala, Ladislav 

7 

IL 

Day, Mark 

10 

19. 

Miller, Mike 

7 

12. 

Duga, Brady 

10 

20. 

Nicolle, Ludovie 

7 

13. 

Fazekas, Miklos 

10 

21. 

Sdiotsman, Jan 

7 

14. 

Flowers, Sue 

10 

22. 

Widyatama, Yudhi 

7 

15. 

Sadetsky, Gregory 

10 

23. 

Heithcock, JG 

6 

16. 

Selengut, Jared 

10 





There are three ways to earn points^ (1) scoring in the top 
5 of any Challenge, (2) being the first per.stm to find a hug in a 
puhli.shed winning solution or, (3) IxHng the first person to 
suggest a Challenge that I use. The points you can win are: 


1st place 

20 pr>ints 

2nd place 

10 points 

3rd place 

7 poinUs 

4th place 

4 points 

5th place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 


Here is Willeke's winning Tetris solution: 
tetris.cp 

Copyright © 2001 

Willeke HJeken 

r 

■1 piece is dropped at e-ich adumn and points are given for 
creating empty cells and adding heiglit. points are subtracted 
Ibr fitting in existing holes, the column with the It west 
score win.s. the moves to drtjp the piece in the winning 
column are placed in an array. In subsequent calls of Tetris 
the next move is returned. 

this is a low tech solution without using the next piece or 
the possibility to move a piece after it dropped. 

7 

/finclude <stdia,h) 
if Include < string. h> 

if Include 'Tetris *h" 

^define kPieceSiae 7 
ifdefine kHalfPieceSize 3 
#deflne kMaxBoardSi^eSize 236 
Idefine kMaxWrRotations 4 

typedef struct Plecelnfo [ 

long pieceLeft, pleceRight, pleeeTop, pieceBottom; 
long ncOfRorations: 

\ Pieceinfo: 


Fight Boredom 

Let’s face it; Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- Vie w-Controller 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It's like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B«0*W»E*R*S 

Development 
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static const Piece ‘gGaiiePieces; 

static MoveTypc gMovesToDo[CkHaxBoardSizeSiEe / 2) + 3]; 

// (m£x board sbx/2) lefts or rights + 2 rotations + drop 
static Piecelnfo 'gPleceInfo: 
static long gNrKovesToDo* gMoveNr: 
static long gLastPieceIndex» glastNextPiecelndex: 
static long gNumRows, gHumCols; 
static long gNujuPieceTypes* gMaxPieceSlze; 


PieceFils 

static short PleceFits(const Board gameBoard. long 
*theTcipOfPieces, 

Piece theActlvePlece. 
long theFleceLeft. long thePieceRlght. 
long thePieceTopp long thePieceBottoaip 
long tbeRow* long theCol, 
short theHustPitlnBoard) 

// dieck if the piece will fit on the boand at 
// poi>jtion (theRoWpth<.<oI),if thcMusiFitlnBoaixl tJicn 
// the total piece has to be on the board 
[ 

long aRowOffsetp aColOffset: 
long aRow, aCol; 


if (gameBoardlaRowOffset + aRow][aColOffset + aCol] >= 0) 
return 0; 

) 

] 

return 1: 


HoiaEePiece90 

static void RotatePiece90(Piece theActivePiecep 

long *aPleceLeftp long 

*aPieceRight. 

long ^aPieceTcp, long 

‘aPieceBottom] 

// rotates the piece 90“ clodwisc 

( 

Piece aRotatedPiece: 
long aRowp aCol: 

for (aRow = Q: aRow < kPieceSize: aRowH-} 
for [aCol ^ 0; aCol < kPieceSize; sCol-H-) 
aRotatedPieceLaCol][kPieceSiae ‘ 1 ' aRow] = 
theActlvePlece[aRow][aCol]; 
memcpyttheActivaPiece, aRotatedPiece, sizeof(Piece)); 


aRowOffset ^ theRow - thePleceBottom - li 
aColOffset = theCol - kHalfPleceSize: 

for (aRow ™ thePieceTop; aRow <= thePieceBottoin: aRow++) 
for (aCol = thePieceLeft: aCol <= thePieceRight: aCol++) 
1 

if {theActivePlece[aRow] [aCol]) 

I 

if [aRowOffset + aRow < 0) 
if (theHustFitlnBoardl 
return 0; 
else 
break: 

if (tbeMustFitInBoard) 

If (aRowOffset + aRow 

theTopOfPieces[aColOffset + aCol]) 
return 0; 


BasePlant 

200 ciasses to enhance PowerPfant^^ 


• AppleEvents 

• AppleScript 

• Collection Manager 

• Data Browser 

• Disk Item Filter 

• Folder Parser 
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• Multiprocessing 

• Preferences Manager 
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• Window Proxy 

And Much More! 
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$35 For personai freeware and shareware 
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aRow ■ *aPieceLeft; 

‘aPieceLeft = kPleceSize - 1 - 'aPieceBottom; 
'^aPieceBottotn = *aPieceRight: 

*aFieceRight = kPieceSize - 1 ^ 'aPieceTap; 
•aPleceTop “ aRow; 


static void RotatePiecelBO[Piece theActlvePlece. 

long *aPieceLeft. long 

‘aPieceRightt 

long ‘aPleceTop, long 

‘aPieceBottom) 
ff rotates the piece 180“ 

I 


RotarePieceieO 


Piece aRotatedPlece; 
long aRow. aCol; 


for (aRow “ 0; aRow i kPieceSizei aRow++) 
for (aCol = 0: aCol < kPleceSlze; aCol++) 

aRotatedPiece[kPieceSize - 1 - aRow]fkPieceSize - 1 - 

aCol] 

“ theActlvePlece[aRow]IaCol]; 
memepy(theActlvePlece, aRotatedPiece. sizeof(Piece)); 


aRow ” *aPieceTop: 

^aPleceTop " kPleceSize - 1 *aPieceBottom; 
‘aPleceBottom = kPieceSize - 1 - aRow; 
aRow *aPieceLeft; 

'aPieceLeft “ kPieceSize ■ 1 - •aPieceRight: 
‘'aPieceRight = kPieceSize - 1 - aRow; 


Rotate Piecc270 

static void RotatePiece270(Piece theActlvePlece. 

long ‘aPlecefeft, long 

'aPieceRight. 

long ‘aPieceTop. long 

‘aPieceBottom.) 

// routes the piece 90“ eounter clockwise 
I 

Piece aRotatedPiece; 
long aRow. aCol : 

for [aRow ^ 0; aRow < kPieceSize; aRow++) 
for (aCol 0; aCol < kPieceSize; aCol+f) 

aRotatedPlece[kPieceSize ■ 1 - aCol] [aRow] == 
theActlvePlece[aRow] [aCol]: 
menepy[theActivePiece. aRotatedPiece. sizeof[Piece)J; 

aRow “ 'aPieceTop; 

‘aPleceTop = kPieceSize - 1 - ‘aPieceRight; 

‘aPieceRight ^ ‘aPieceBottom: 

‘aPieceflottom “ kPieceSize - 1 - ‘aPieceLeft; 

•aPieceLeft = aRow; 


FmdGimpletedLines 

static void FlndCompletedLines(const Board gameBoard. 
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short 


theCoHipietedLines [kPieceSize] , 

long ‘theNrCompletedLines t 
Piece theActivePiece. 
long thePieceLeft, long 

thePieceRight. 

long thePieceTop. long 

thePieceBottom* 

long theRoVi. long theCol) 

// find the Mnes th^t are completed and will disappear after the piece dropped 

i 

long aRowOffset* aColOffset; 
long aRow, aCol: 

aRowOffset = theRow - thePleceBottom - U 
aColOffset = theCol - kHalfFieceSlzar 

fot (aRov = 0: aRow < kPleceSize; aRowH-) 
theCtnBpletsdLtneE [aRov] 0: 

‘theNrCompletetiLines = Or 

fox {aRov = thePieceTop: aRow C“ thePieceBottom: aRow++) 

[ 

theCompletedLinesURowJ = Ir 

for [aCol = thePieceLeft; aCol <“ thePieceRight; aCoI++) 
if ((ttheActivePiece[aRov] [aCol]) 

(gameBoard[aRowOffset + aRow][aColOffset + aCol] = 

-D) 

I 

theCompletedlinea [aRow] ^ 0: 
break; 

1 

If [theCoapietedLine s[aRow]) 

1 

for taCol = 0; aCol < aColOffset + thePieceLeft: 

aCol++) 

if (gaineBoard[aRowOffset f aRow] [aCol] = -l) 

t 

theCompletedLinea[aRovI ” 0; 
break: 


I 

] 

if [theConipletedlitiesURowI) 

( 

for {aCol = aColOffset + thePieceRlght + 1; 
aCol < gNumCols: aCol++) 
if (gameBoardlaRowOffset + aRow][aGolj = -1] 
I 

theComp letedLines[aRow] = 0; 
break: 

I 

I 

If (theCompletedLinesIaRowj) 

C * theNr C omplet edLine s}++: 

I 

1 


CountEmptySpaces 

static long ConntEinptySpaces (long 'theTopOfPieces ♦ 

short 

th€CoiHpletedLines[kPieceSize] » i 

Piece theActivePlece, 
long thePieceLeft» long 

thePieceRight. 

long thePieceTopt long 

thePleceRottom. 

long theRow, long theCol) 

// count the empw cells as a asult of the pieee being dmpiKtJ 
// at tlieCoL don't include ilte empty cells tliat wUJ be part 
// of the big space at the top after dc completed lines arc removed 
1 

long aRovCffset, aColOffset: 
long aRov. aCol* aW r Of Empty Spaces r 

aRowOffset = theRov - thePiecaBottom - 1r 
aColOffset = theCol - kRalfPleceSize; 
alJrOfEkpty Spaces = 0; 

for {aCol ^ thePieceLeft; aCol <= thePieceRight; aCol++) 

{ 

short aPiecelnColumn = 0; 
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Software for the business world revolves around SQL 
database systems like Oracle, SQLServer, Sybase, DB2, 
Informix and InterBase. Database designers can create 
logical and physical data models with MacA&D, then 
generate SQL for tables, views, constraints, assertions, 
triggers, indexes, procedures and other SQL elements. 

Designers can toggle between logical and physical models 
and show tables with full attribute lists, just primary and 
foreign keys or customized to show specific attributes. 

MacTranslator generates a data model from existing SQL. 
MacA&D and MacTranslator use namespaces to simplify 
team development, enable powerful organizational and 
reporting features, partition complex systems and map 
design elements to specific SQL schemas. 


Excel Software 

Software En^itieenng Made Ea,'iy 

505 - 771-3719 

iiiniiw.8xcelsanware.caiii 505 7713718 

Iiifoniuibcni «i soflVTire models di^gs oncdiodv Add eoSmre 
mginoaTiip Inoln tnr ^cinlwhAnd >cwnpu1em 


SQL database design in MacA&D 


MacAAO. MacTFiaiislator. WtnAdltD, WjnTraji&laiDJf and QukkCStC are tiademariL'S of Excel 
Sofluran:. © 200 L Other brajid and pmduizt nameL^ are tnidemailu of their i'es|)ecL[vc hnIderR. 

















































Take OpenBase SQl for a Test Flight Today! 


pnBase SQL 6.5 

h high-performance 
^Qlabase for MacOS X 


■HBASE flATURES 


IBC Driver 


ebObjed^ Adaptors 
■ALliasic Plugin 
ulti-Threflded Server 


iw Level Locking 
M MB Seordioble Blobs 
ptabcEse Replication 


gtobose Management Took 
rgphical Schema Design Tools 
eniote Adininistrcrtion 


process ovor 2 milim 
jsQCtions each day. 
mBase performance has 


outstanding^ 

hfArrlwQhMm 


Get Your FREE Developer's license at www.openbase.com 


OpenBase' 

I«11 IHI r- ij. H11 


for CaRov = thePieceTop; aRow <“ tbeFieceBattcJiB: aRQ>rf-+) 
If (theActivePiecetaRow][aCoI] && 

(1theCompletedLines[aRow])) 

I 

aPieeernColutEin “ 
break; 

] 

if (aPieceInColuffinJ 

! 

aRow = thePieceTop; 

while {£! theActivePiece [aRow] [aColJ ) fifir 
(aRov thePieceBottom)) 

aRow+i; 

while f£aRow + aRowOffset < 

theTopOfPiecGs[aColOffset 1 aCol]) H 
(aRow the PieceBottom)) 

f 

if (! theActivePieceURow] laCol]) 
aNrOfEmptySpacefl++: 
aRDVf+i; 

[ 

if (aRow + aRowOffset < theTopOfFieces[aColOffset + 

aCoi]) 

if £(theTopOfPieces[aColOffEet + aGol] - aRow - 
aRowOffset) 

'> gMaxPieceSlze) 

aNrOfEmptySpaces 1= gMaxPieceSize: 
else 

aNrOfEmptySpaces -1-= (theTopOfPieces [aColOffset + 

aCol] - 

aRow - 

aRowOffset): 

) 

! 

return aNrOfEmptySpaces; 

J 


CountTouches 

static long CnuntToiiches (const Board gemeBoardp 

long ‘theTopOfPieces, Piece 

theActivePiece, 

long theFieceLeft, long 

tbePieceRiglit. 

long thePieceTop* long 


tbePieqeEottom* 


long theRow. long theCol) 
// count at how rasiny cdbi the piece wiU touch the pieces on 
// the hoard, subtract points for creating deep pits 


long aRowOffset. aColOffset: 
long aRow* aGol, aNrOfTouches; 


aRowOffset ■ theRow * theFieceBottoin - 1; 
aColOffset ^ theCol - kHalfPieceSlzer 
aNrOfTouches ^ 0; 

for £aRow ■■ thePieceTop: aRow thePieceBottoni; aRow++) 
for (aCol = thePleceLeft; aCol <= thePleceRlght: aCol++) 
if (theActivePiece[aRow][aColJ) 

I 


- 11 


// touches on the left 
if (aColOffset + aCol = 0) 

sNrOfTouches++j 

else 

if £££aCol ^ thePieceLeft) || 

(! theActivePiece [aRow] [aCol - 1] )) 6f& 
[gameBoard [aRowOffset + aRow] [aColOffset aCol 

!= -15) 


+ 1] 


aCol] 


aNrOfTouches++; 

// touches on the right 

If (aColOffset i aCol ^ gNumCols - 1) 
aMrOfTouches-f-t; 
else 

if ({(aCol = thePleceRlght) || 

(! theActivePiece [aRow] [aCol + 1])) && 

£gameBoard[aRowOffset + aRow][aColOffset + aCol 

1= -D) 

aNrOfTouches++; 

// touches on the bottom 

if [aRowOffset + aRow — gNumRows - 1) 
aHrOfTouches+i; 
else 

if £((aRow ^ thePieceBottom) || 

(!theActivePiece[aRow + l][aCol])) 

(gameBoard[aRowOffset + aRow F 1][aColOffset + 

1= -D) 
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aKrOfTouche3++: 

1 

// check for deep pits 

if {(aColOfffiet + thePleceLeft > 0) && 

(theTopOfPiecea[aColOffset + thePleceLeft - 1] > 
aRowOffset + thePleceBottooi + 1)) 

I 

aNrOfTouches 

((theTopOfPieces[aGolOffset + thePieceLeft - 1]) - 
(aRowOffset “P thePieceTop + 1}): 
aRow = thePieceTop: 

while CItheActivePiece[aRow][thePieceLeft]) 

I 

aRow-; 

aNrOfTouches++; 


if [faColOffset + thePieceRight < gNumCols - 1) && 

(theTopOfPieces[aColOffset + thePieceRight + Ij > 
aRovOffset + thePlaceBottom + 1)) 

( 

aNrOfTouches ’= ((theXopOfPiecesUColOffset + 

thePieceRight +1]) - 
[aRowOffset i thePieceTop + 

D); 

aRow = thePieceTop; 

while (ItheActivePiece [aRow][thePleceRlgbt]) 
aRow^: 

aMrOfTouches-H-: 

1 

return aNrOfTouches: 


ViilidiVltivc 

static short ValidMove(const Board gameloard. 

short activePieceTypeIndex, 
long 'theTopOfPieces> long 

theTapTopOfPleces. 

long theCol, long theEotation) 

// Liieck If the piece can reach its CQlnmn without 


SPOTLIQUTl 

seven times faster 


free demo 
www.onyx-tech.com 


find memory errors o(ifom<jf/cra//y in source 
Code Fragment Support 
Leak Detection 
Toolbox Parameter Checking 





// colliding with pieces on the board 
I 

longaCol. aRow, aRrMovesToDo; 

Piece anActivePiece: 

long aPieceLeft r aPieceRlght. aPieceTop. aPieceiBottom: 

manicpy(anActivePlece. gGamePieees[activePieceTypeIndex], 
sixeof(Piece)): 

aPieceLeft = gPiecelnfo [activePleceTypelndex] .pleceLeft: 
aPieceRight ^ gPiecelnfoUctiveFieceTypeIndexJ.pieceRlght; 
aPieceTop = gPiecelnfo[activePleceTypeTndex].pieceTop: 
aPieceBottoni - gPieceInfo[actlvePleceTypeIiidax] ,pieceBottom; 

aRow = 1 - aPieceBottoiu: 

// count moves 
aHrMovesToDo = 0; 
switch (theRotatlon) 

r 

case 0: 

break; 
case 1; 

aNrMovesToD 0 ++I 
break; 
case 2: 

aKrMovesToDo++: 
aMrKovesToDci++; 
break: 
case 3; 

aNrHovesToDo'H'; 

break: 


if (theCol > gNumCols / 2) 

aHrMovesToDo += theCol - gNuraCols / 2; 
else 

aNrHovesToDo += gNumCols / 2 - theCol: 


// check If the piece can move without hitting pieces on the bosnd 
if MrMovesToDa >“ theTopTopOfFieecs) 

switch (theRotatlon) 


case 0: 

break: 
case l! 

RotatePlece90(anActivePlece. 

&aPieceLeftt 4aPieceRight, 
&a PieceTop. &aFiec eBott nm)| 

aRow++: 
break: 
case 2: 

RotatePiecelSO(anActivePiece. AaPieceLeft, 
SiaPieceRight, iaPleceTop, 
^aPieceSottoru): 

aRow+i: 
aRow++; 
break: 
case 3: 

RotateFlece270(anActivePiece* 

AaPieccLeft* ^aPieceRight, 
&a P iec eTop, ^Ia Pi e C eBo 11 ora); 

aRowH^r 
break: 


) 

aRow sFleceBottom: 

for (aCol * gNumCols / 2 + 1: aCol < theCol: aCol++) 
if (tPieceFlts(garaeEQard, theTopOfPieces* anActivePiece* 
aPieceLeft. aPieceRight. aPieceTop, 

aPleceBottcmi* 

aRow + (aCol - (gNumCols / 2 + I)). 

aCol* 0)) 


return 0: 

for (aCol “ gNumCols / 2 - 1: aCol > theCol; aCol-) 

if {!PleceFits(gameBoard* theTopOfPieces. anActivePiece, 
aPieceLeft* aPieceRight* aPieceTop* 


aPieceBottom, 


aCol* 0)) 


aRow + ((gNumCols / 2 - 1) - aCol)* 


return 0; 
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return 1: 
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MovrPkre 

static void MovePiece(const Board ^aineBoardt 

short activePieceTypelodex) 

// derermine the column for the piece :uid prepare the moves 

t 

Piece anActivePie cei 

long aPieceLeft* aPieceRight, aPieceTop, aPieceBottom; 

long aRow, aCol* aRotation; 

long aTopOfPieces[kMaxBoardSizsSizs]; 

long aBattomTopRoWp aTopTopRow: 

long aColScore fkMaxNrRotations][kMaxSoardSiaeSlae ]i 

long aBestScore, aBestColt aBestKotstion^ 

long anExtraScotEi aMrCompletedLlneB■ 

short aCompietedLin.es [kPieceSiae]: 

short aValidHove; 

jiieiiicpy(anActivePlece. gGamePieces [activePieceTypeIndex] < 
siseoftPiece)); 

aPieceLeft = gPlecelnfo[activePieceTypeIndex],pieceLeft; 
aPieceRight = gPiecelnfo[activePieceTypeIndex].pleceRight: 
aPieceTop = gPiecelnfoLactivePieceTypelndexJ.pieceTop: 
aPieceBottom == gPiec.elnfo [activePieceTypeIndex], pieceBottom: 

// find top of pieces in board 

aBottoniTopRow “ 0; 

aTopTopRow = gJJumCols: 

for [aCol = Ot aCol < gNumColfi: aCol-H-) 

i 

aRow “ 0; 

while ((aRow < gNmoRows) kk 

(gameBoardlaRow] [aCol] = -l3) aRowM-: 
aTopOfPieces[aCol] “ aRow: 
if (aSottoniTopRow < aRow) 
aBottoniTopRow = aRow: 
if (aTopTopRow > aRow) 
aTopTopRow “ aRow: 

1 


// find wheitr tlio piece fits best 
for (aRotation = 0: 
aRotatlon ^ 

gPieceInfo[activePieceTypelndex].nrOfRorations: 
aRotatioir++} 

I 

for (aCol = 0: aCol < gfJumCols: aCoH-+) 

I 

aColBcore[aRotation][aCol] " 1000000; 
if ({aCol >= kHalfPieceSize - aPieceLeft) kk 

(aCol < gNumColfl - aPieceRight + kHaIfPieceSize)) 

[ 

aRow = aTopOfPieces[aCol] + kPieceSize - 1; 
if (aRow > aBottomTopRow) 
aRow “ aBottomTopRow: 

while [(IPieceRits(gameBoard, aTopOfPieces, aoActivePiece, 
aPieceLeft, aPieceRight, aPieceTop, aPieceBottom, 
aRow, aCoIt 1)) 

(aRow )* 0)3' 
aRow^: 

if (aRow > (aPieceBottom - aPieceTop - 1)) 

( 

aColScore[aRotatlon][aCol] - 
[(aBottomTopRow - aRow) -i- 
[aPieceBottom - aPieceTop)) * 2; 

Find Comp 1 etedLinea (gameBoard, aConrpletedLines, 
^aUrCompletedLines. anActivePiece, 
aPieceLeft, aPieceRight, aPieceTop, aPieceBottom* 
aRow, aCol): 

anKxttaScore = CountEmptySpaces(aTopOfPieces, 
aCompletedLines, anActivePiece, 
aPieceLeft, aPieceRight, aPieceTop, aPieceBottom* 
aRow, aCol): 

aColScore[aRotatlon][aColJ += anExtraScore * 5: 
anExtraScore = GountTouches(gameBoard* 
aTopOfPieces, anActivePiece* 
aPieceLeft* aPieceRight* aPieceTop* aPieceBottom, 
aRow* aCol): 

aColScore[aRotatlon][aCol] -= anExtraScore: 
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A New System is Coming 



netOctopus is ready. Are you? 


Mac OS X is coming. Ifs right around the corner. You may 
be going through your preparation checklist right now, 
wondering if you have enough time: 

^ inventory all installed software 

✓ Check software versions 

✓ Check hard disks and memory on all computers 

✓ identify hardware upgrade needs 

✓ Print summary reports 


With netOctopus, you can do all of that with a few mouse 
clicks. Then, when OS X arrives, get the new version of 
netOctopus, and use it to distribute all of your new software 
throughout your network seamlessly, 

Timbuktu Pro, the # i remote control and file 
transfer software for the Mac, integrates seam¬ 
lessly into netOctopus, for even greater nef- 
Ti mbuktu work support! 



With netOctopus, you would practically be ready for OS X today. 
Without netOctopus, you may be running out of time. 


neBa 



www.netoctopus.com 
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) 

RqtatePiece90[anActivePiece. 

&aPieceLeft, &aPieceMght, &aPieceTop. 
&aPieceBottom); 

} 

aBestCol = Oj 
aBestRotatlon = Oj 
aValidMove ^ 0; 
while [!aValidMove) 

I 

aBestScore = lOOOOOO; 
far (aRotation = 0: 
aRotatioa < 

fePlecelnfo[activePleceTypelndex].nrOfRoratIona; 
aRotatlon-H-) 

far [aCol = Dj aCol < gNumCola: aCcl+f) 

If CaColScare[aRQtation][aCol] < aBestScore) 

E 

aBestScore ^ aColScgrelaRotation][aCol]^ 
aBeatCal = aCol: 
aBestRotatlon * aRotation: 

1 

if (aB eats core < 1000000) //found valid move 

E 

if (ValldMoveEgameBoardp activePieceTypeladex, 
aTopOfPleceSp aTopTopRow, aBestCol, 
aBestRotatlon)) 

aValldMove - 1; 
else 

aColScorelaBestRotatlDa][aBestCol] = 1000000; 

else 

[ 

// Qo valid movi^, give up 
aBestCol = gNimCola / 2: 
aBestRotatlon = 0: 
aValldPtove = 1; 

I 

f 

// prepare movcH 
gNrMovesToDo - 0; 
switch (aBeatRotation) 

I 

case 1: 

gMovesToDo[gNrMovesToDo] ^ kRatateClockwlse; 
gNrMovesToDa++: 
break; 
case 2^ 

gHovesToDoIgNrHovesToDo] ^ kRotateClockwlse; 
gNrMovesToDcr+f: 

gMovesToDo [gHrMovesToDo] - kRotateClockwlse: 
gNcMovesToDo-H-: 
break; 
case 3; 

gMovesToDo[gNtMovesToDo] = kRotateCounterClackwise; 
gNrMoveeTaDo++: 
break: 
f 

if (aBestCol > gMumCols / 2) 

for (aCol = gNumCols / 2: aCol < aBestCol: aColff) 

( 

gMovesToDo [gNrHovesToDal = kMoveRight: 
gNrMoveBToDo++; 

I 

else 

for (aCol = aflefitCol: aCol < gNutsCols / 2; aCol-l-+) 

gMoV e s To Do[gN rMov e sToDo] “ kMov eLe ft; 
gNrMovefiToDot^: 

[ 

gMovesToDo[gNrMovesToDo] ^ kDrop; 
gNrMoveETDDo++; 

gMovesToDofgNrHovesTQDo] ^ kNoMove; 
gNrMovesToDo++; 


(jCtPiccelnfb 

static void GetPleceInfol) 

// detennine ihe bounds of ihc piece and if rotating 
// the piece results in the same piece 
i 

long 1; 

for (i = 0; i < gNumPieceTypes; 1++) 

long aPleceLeft = kPieceSize - 1. aPlecieRlght = 0; 
long aPieceTop = kPieceSize - 1. aPieceBottom =*= Q; 

Piece anActivePiece; 

long aRow, aCol, aRowOffset, aColOffset: 

aho r t aPiece sMatch; 

laeincpy(anActivePiece. gGamePlecesli] . sizeof (Piece)); 
for (aRow = 0; aRow < kPieceSize: aRow++) 
for (aCol ^ 0; aCol < kPieceSize; aCol++) 

If (anActivePiece[aRow][aCol]) 

( 

if (aRow < aPieceTop) 
aPieceTop ^ aRow; 

If [aRow > aPieceBottom) 
aPieceBottom “ aRow; 
if [aCol < aPleceLeft) 
aPieeeLeft ^ aCol; 
if (aCol > aPieceRlgbt} 
aPieceRlght - aCol; 

gPieceInfD[i].pieceLeft ^ aPieeeLeft: 
gPieceInfo[l]-pieceRight = aPieceRlght: 
gPieceInfo[i].pleceTop * aPieceTop; 
gPiecelnfoilKpieceBottoiti = aPieceBottom; 

if CaPieceRight - aPleceLeft > gMaxPleceSl^e) 
gHaxPieceSize = aPieceRlght - aPleceLeft; 
if CaPieceBortom - aPieceTop > gMaxPieceSlze) 
gMaxPieceSize - aPieceBottom * aPieceTop; 

gPiecelnfoIi].nrOfRorations = kMaxNrRotatlans; 

Ro tat e Piec e 9 0[anAc tivePle c e, 

AaPleceLeft, &aPleceRight, ^aPieceTop, 

&aPieceBottom); 

if ((aPieceRlght - aPieeeLeft) “ (aPieceBottom - 
aPieceTop)) 

I 

aPiecesMatch ^ 1; 

aRowOffset = gPieceInfo[l].pieceTop - aPieceTop; 
aColOffset " gPleceInfo[l].pieceLeft - aPieeeLeft; 
for (aRow = aPieceTop: aRow aPieceBottotii; aRow++) 
for (aCol = aPieeeLeft; aCol <= aPieceRlght: aCol++) 
if {(anActivePiece [aRow] [aCol] &£( 

!gGai 0 ePieces [i] [aRow + aRowOffset] (aCol + 
aColOffset]) [I 

(SanActivePlece[aRow] [aCo1J &^ 
gCamePleceE[1][aRow + 

aRowOffset][aCol + aColOffset])) 
aPiecesMatch = 0: 
if (aPlecesHatch) 

gPieceInfoUj .nrOfRorations ^ 1; 

I 

if (gPiecelnfoliJ.nrOfRoratlons — kHaxNrRotations) 

[ 

RotatePiece90(anActivePiece, 

AaFieceLeft. SiaPieceRight. fcaPieceTop. 
SaPieceBottom); 

aPiecesMatch = 1; 

aRowGffset = gPiecelnfoti].pieceTop - aPieceTop; 
aColOffset “ gPiecelnfo[ij ,pieceLeft - aPieeeLeft; 
for (aRow = aPieceTop: aRow <= aPieceBottom: aRowtt) 
for (aCol = aPieeeLeft; aCol <= aPleceRigbt; aCol-H-) 
if ((anActivePiece[aRow][aCol] && 
igGamePieces[i][aRow + 

aRowOffset][aCol + aColOffset]) 

(!anActivePiec e[aRow][aColJ && 
gGamePiecesli][aRow + 

aRowOffset][aCol + aColOffset])) 
aPiecesMatch = 0; 
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if (aPlecesHatch) 

gPleceInfo[i].nrOfKorations = 2: 

J 

1 

] 


InitTttris 

void LnitTetris{ 

short boardWidth♦ r width of board In cclb 7 

short b oardHeight. /* height of board in cells 7 

short numPieceTypo s. t number of types of pieces V 

const Piece gamePieces [ ] , T piccei to play 7 
long timeToPlay t game time, in milliseconds 7 

) 1 

gNumRowE = boardHeight; 

gNumCols = boardWidth; 

gNumPieceTypeE “ numPieceTypes: 

gGamePieces game Pieces: 

gNrMovesToDo = 0; 

gMoveNr = 0; 

gLastPieceIndex "" -1: 

glaatNextPietelndex = -1; 

gPiecelnfo = new Fiecelnfo[gHumPleceTypes]; 

gMaxPleceSize " 0: 

GetPiecelnfoC): 

gMaxPleceSize-H-; 


Tetris 

MoveType P mme aaive pieta^ */ Tetris{ 
const Eoerd gameBoard, 

P airrent state of 3ie g;imc board, 
bottom now is fboanJ Height-] left Ltjinmn is lOj 7 

short activePieceT^elndex. /* index into gamePieces of active piece 7 
short next PieceTypelndex, P index into gamePieces of next piece 7 
long pointsEarned * P number of points earned thus far V 

1 ong t iraeXoGo P time remaining, in milliseconds */ 

) I 

// try^ to detect a new piece, 

// will fai] when a piece appears three times in a row 
If {(gLastPiecelndex 1= activePieceTypelndex} || 
(glastNextPiecelndax != nextPieceTypeIndex)) 
gMoveMr = gNrMovesToDo: 
gLastPieceIndex = activePieceTypeIndex: 
glastNexlPiecelndex = nextPleceTypelndex: 

if (gMovsNr >= gNrMovesToEo) 

I 

// calculate the moves for a new piece 

MovePiece[gameBoard* activePleceTypelndex); 

gMoveNr = 0; 

1 

// return next move 

return gMovesToDo [gl1oveHr++]; 


TermTetris 

void TermTetris(void) ! 
delete [] gPiecelnfo: 

I 


m 



Porting & Development 
Showcase 


Mac OS X 

Making the Move 


With i/JrjfT/ X/S jy just over the 
Mac dcYeloper^ everywhere have a 
major need for CAB BON and 
application porting, ASIA user interface 
implementation, and iililH development 
services. Toward that end, several 
high-quality engineering 

firms, in association with the ^PPLI 
mwm [ONNECliQW. are offering these 
services at very discounts 

to all Select and Premier members. 


The following pages 
are those vendors that 
are part of the Mac OS X 
Porting & Development Showcase. 
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we are paving the 

Sixteen years of experience coupled with the resources and Flexibility you need.,, 
just furn the key. Prosoft Engineering Inc., offers unsurpassed advantages 
including professional engineers with in-depth knowledge of OS X, 
partnerships with the top industry leaders, and corporate 
headquarters located in the hear! of Silicon Valley. | 










































road for your success 

Prosoft Engineering Inc*, is your source for cost-effective, on-lime, custom cross- 
platform software solutions and services* By uniquely integrating Software 
Engineering, Quality Assurance, and Project Management, 
we are poving the road to success on your next project 
(925) 426-6100 • www.prosoftengxom • info@prosofteng.com 



engineering inc* 


Prepare for a 
smooth ride... 









































Without sufficient resources or the right expertise, your project is at risk of shipping late. 
Atimi guarantees reliable and timely Macintosh software development that enables you 
to get to market on schedule, delighting both you and your customer. With a wide array 
of technical expertise, Atimi offers a full range of services: 

Classic Mac OS to Mac OS X application porting (Carbon and Cocoa) | Windows to 
Mac OS application porting | Application development | Driver development 
(printer, PostScript, USB, Firewire, etc.) | Networking development (wireless and wireline) 

Call 604.813.1319 or visit us at www.atimi.com. 

Join us at WWDC! 



Macintosh software development. On-time. 




□ Eat your vegetables. 

□ Exercise every day. 
2 Port to Mac OS X. 

□ Call your mom. 


All of these are good for you. 
We can make one of them easy. | 

Since 1989, The Omni Group has worked with the technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and foiled whatever path you choose. 

That's been our business for years. No matter what kind of produa you have, we can get it up under 
OS X, fast: 

• Real games: We ported id's Doom and C^iake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's FrameMaker to NEXTSTEP and Sun's Concurrence to OpenStep/Solarls. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

• Serious drivers: We ported 3dfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmnlWeb, the only native OS X web browser, and C^niPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


The Omni Group 



2707 Northeast Blakeley Street saIe 5 #omnifiFDUp.coni 

Seattle, Washington 98105-3118 80O.3i5.OMNI x20! 

www.omnlgroup.com/consultlng 206.523.4152 x20! 


Mar C?SX. WEXTSlTIPr 4Jid tJpenStep axt uttdieniarks of Appk. Actrihat Mtd fratneklAkontre iTudumarit of Adobe Inc. Qpak: und IkstiiB are intdemarka of Id Sofiiw ape. Stdiirt* and Conrurr^cp are ttsul 

of Sun {hwlie b a i rudeAiari dfOniclc: PUde dnd Vooden arc iraddiAirlA of Mtn. ‘^Thc Oennl OnHip." UttuiIWc^ Oioltillll', itnd ihc Uitinl G«in Ijogio an* oun. Hmse doti'i aue us. And rail your 
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Fly by our White Paper, Mac (^XMi^atmi at 

wwT^;paralleLcoin 


Call usat877-PARAfm 


When something unusual occurs, it takes 
thoughtful advisors to inter[)rel meaning and 
impact. Moving your software up to Mx OS X? 
It’s not your usual migration— so you need an 
expert guide who knows how to get you upgraded 
without getting lost. As tlie Midwest’s largest 
Apple* developer. Parallel is the OS X transition 
expert. Well gm uncommon insight to your 
application planning, development, and 
successful migration, 









X 

Product X 


You can’t show your 
product’s future... 


* I « 0 • ■ t 


...until its ability to 
perform is optimized 
for the present. 





Come to the Mac OS Experts 


Red Rock Software specializes in Macintosh software development. 
Our team of senior engineers averages over 10 years of development 
experience on the Macintosh platform. Our experience and expertise 
has gained us the trust of companies like Apple Computer, Iomega 
Corporation and Sorenson Media. 

Let our experts make your product compatible with Mac Os X. 

* Aqua Interface Implementation 

• Os X Carbon Porting 

« Os X Native Cocoa Application Development 



O C K 


s 


Call Red Rock at 888,689,3038 
or visit us online at www.redrocksw.com 
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415.491.221 

www.shadetreeinc.co 


Software Development 
Outsourcing Since 1990 













DetMlopmerii 


DarWi 


Cross Platform Migration 


Have the best engineers aroandi. 
If it's Mac, tue've done it. 


& 15 Year Track Record of Delivering Consistent Customer Satisfaction 
9 Highly Skilled Quality Assurance 6s Testing Team 
9 Development Centers Nationwide 

9 Over 175 Engineers VANTEON 


® Extensive Configuration Testing Facilities 


Delivering Innovative Engineering Solutions 


For more information please call 1-800-266-5046, e-mail at mac@vanteon.com or visit us at www.vanteon.com 







METWORKiniC 


By Chris Kilboum 

Editied by JiAstin W. Newton, Senior Director, Networking and Telecommunications, NetZero, Inc. 

Multihoming Your Network Using the 
Border Gateway Protocol (BGP) 


What is BGP? 

BGP stands for Border Gateway Protocol and is generally 
used as an exterior gateway network routing protocol. When it 
is used as an exterior protocol, it only passes information about 
external network information it receives, and di>es not transmit 
any information about internal network routes or structures to 
the outside world 

BGP is only useful if you are multihomed (have more 
than one Internet connection.) If you only have one Internet 
connection, you only have one path to the Internet, and BGP 
would only ever announce that one path to your network. If 
that one link goes dowm, there is no failover that can he done 
via BGP. A network topology with only one path would be 
much better served by using static IP routes. 

BGP allows for the announcement to the rest of the 
Internet that you have more than one path into your 
network. This means that any traffic destined for your 
network has a redundant path and having redundant paths 
into your network unshackles you from a single point of 
network transit failure. 

This i.s generally accepted to be a Very Good Thing due 
to the increa.sed uptime and accessibiiity of your network 
when running BGR 

History of BGP 

BGP had its roots in EGP (Exterior Gateway Protocol) as put 
forth in October of 198211] which introduced the key concepts of 
autonomous systems, network neighbors, tlie routing core and 
routing updates. 

EGP described a system of autonomous systems of networks 
which exchanged network reachability iiifornnation to network 
neighbors. Tliis was done via routing updates when tlie network 
status changed state (up/down) in the core as reported l>y 
neighboring networks. 

Since 1982, EGP and then BGP protocols have gone tlirough 


several changes to support new technologies and die challenges 
of scaling die Internet routing system. Currendy, BGP4 is actively 
deployed in the 'core* of the Internet, 

Today, the core of tlie Internet is oinsidered to be network mesh 
of lx)undary routers betw'een autonomous netw^orks. 

Format and Workings of BGP 

BGP is used to pass network route information betw^een 
autonomous netwwks on the Internet, Unlike active routing 
protocols like AppleTalk that periodically pass the entire 
route table, BGP only passes network change information 
wiien it occurs, 

BGP messages pas^sed lx?tween network neightx>rs M into one 
of four categories^ open messiiges, ufidate messages, notification 
messages, and keep-alive messages.[2] 

Open messages are used to establish a routing session 
between network neighbors, and include the BGP version 
number being used, the ASN (Autonomous System Number) of 
the originator, a hold time used to set session timing to prevent 
message flocxling, a BGI^ identifier which is set to an IP address 
of the sender and optional parameter information which is 
generally used for security. 

Update messages serve double duty by passing new route 
announcements with network path information and by 
informing neighl>ors of withdrawn routes and networks. 

Keep-alive messages are exchanged betw^een neighbors to 
let neighix)rs know^ that they are still there and routing. If a 
neighbor does not receive a keep-alive message, it will back off 
sending data to that neighbor until a new open mes.sage is 
received and wathdraw^ those routes from the local routing table. 

Notification messages are used to report errors to 
neighbors, and the BGP se.ssion is then closed to prevent 
invalid data to be injected into the routing table. 

BGP neighbors exchange network route information that 
are passed as belonging to a particular ASN, and routing 


Chris KUbourn <chrisk®forest.net> is die Founder and Chief Technical Officer for digital.forest, a server colocation, database- and application-hosting 
company serving clients worldwide. 
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share your high-speed Internet connection and 
protect your data from unauthorized access with the 

Hz\L\HEBroadband Gateway '^:Fanglm 



The NetLINE 


Broadband Gateway 

allows you to share a high-speed Internet 
connection, such as Cable or DSL, with 
multiple computers using just a single IP 
address from your ISR 

The built-in firewall will protect your 
important files by preventing unauthorfred 
access via the Internet. 

Works with both Macs and PCs. Web- 
based configuration makes set-up a breeze. 

Receive a coupon for 
25% off a Farallon hub 
or switch when you 
purchase the NetLINE 
Broadband Gateway, (usoniy) 

For more information contact 
Dr. Farallon at 1-800-613-4954 or 
visit us on the web at www.farallon.com 



Internet 



Cable/DSL 

Modem 




The NetLFKE Broadband Gateway connects between 
your network and your Cable/D$L modem 


imm. 





















decisions are made on ASN reachabiliiy information. The 
shortest ASN path is generally chosen when presented witJi 
multiple paths to a given network.[3] 

Migrating to BGP 

Migrating your network to BGP routing can be a 
challenging process, and it is not for everyone. In fact, the 
Internet community has stringent requirements before you 
can send your first open message to your first BGP neighbor. 

These requirements include being multi homed, having 
a powerful enough router to do BGP routing, being assigned 
your own block of IP address space, and having an ASN 
number assigned to your organization. 

Usually, the first BGP routing you wdll do will be to your 
upstream Internet transit providers. Since each network that 
you connect to may have different requirements, you shotiid 
inquire with your future BGP peers to determine what 
requirements they have. 

The first step, becoming multi-homed, is the easiest. Ail 
you need to have is more than one Internet connection from 
different Internet access providers who w^ll exchange BGP 
routes with you. 

Acquiring a powerful enough router is a little liarder due 
to cost issues. Currently, you need at least 128MB of RAM in 
your router (if you use Cisco gear,) to accept the full Internet 
BGP route table. Router RAM is expensive, and the more 
connections you have to the Internet, the more processing 


SuDerRaport Pro 2.s 

The illlmale reporling lool lor 4lh Dimension ahhllcatlons 


Enhanced User Interface 
Compatible with 4D E.5 & 6.7 
Developer Interface 
Enhanced HTML Interface 
New & Enhanced Commands 



SuperReport Pro combines the power and ease of use of 4th 
Dimension® with an enhanced reporting tool which can create a 
wide variety of reports, From standard columnar style reports, 
to detailed Invoices, to reports which will be distributed within 
your companies intranet or to your corporate web site. 


ASG 


MTeMKTED SOLDTIQflS QFDUP 


Automated Solutions Group 

Phone (7U) 375-4252 • Fax (714) 848-0382 
E-mail: sales@asgsoft.oonn * www.asgsoft.com 


Toll-free (800) 375-4ASG 


RAM — Routers Need It Too! 

As you saw in the main part of the article, this and many 
other types of router uses requires lots of Il\M. And, this isn’t 
just any RAM — it’s the kind that can get expensive quickly for 
several reasons. 

First, the RAM needs to be high quality' and relatively fast, 
Second, is the configuration of the RAM module itself —it’s not 
the same as what you’d buy for your Mac or PC. 

After checking around with router people “in the know", 
we came up with two places to get router RAM. First, is to get it 
from a Cisco reseller. This is the most expensive way to go. 
Second, we found Rocky Mountain RAM, in Boulder, Colorado 
— and saved a considerable amount of money compared to the 
local Cisco reseller. The rep we spoke to was Eric Thomas, 
ethofnas@ram-it.com, 800-543-0932 — and he knew quite a 
bit about Cisco’s, 

Got the RAM, popped it in, and never thought about it 
again. Just as life should be. ISl 


power you will need, There is a fairly active used market 
right now, so be sure to shop around, and compare vendors! 

IP address space allocation is the hardest part of the 
process as networks must meet stringent requirements to 
denionstrale need.[4],[5J There are two methods of obtaining 
IP addre.sses; from a regional IP ^egist^>^ or from one of your 
upstream ISP's. 

Unless your network is already utilizing 2.048 TP addresses 
internally or with dowmstream clients, you w ill not qualify for 
your own addre.ss space allocation from a registiy and w4ll need 
to reque.st space from one of your ISP’s. 

Due to IP address depletion, you should only ask for the 
amtJLini of IP space you really need. While it used to be the 
case that only large IP blocks were routeabte in BGP, small 
hkjcks are now^ commonly routed so there is no need to ask 
for extra IP space any more. 

Once you have been allocated IP addre.ss space from a 
regisuy or yniir ISP and are currently multihomed, you can 
begin the process of applying for an ASN,16] 

ASN's are defined by a l6 bil identification number assigned 
by ARINlTl for Noiih and South Amerkan netwarrks, RTPE[8] for 
European and African netw^orks, and APN1CI9] for Asian and 
Pacific netw'orks. These organizations are also responsible for IP 
addre.ss allocations for their respective regions. 

It is po,ssible to obtain an ASN without an IP network 
addres,s allocation, but its utility is somewhat limited. This is 
because ASN's ofxained this w^ay are limited to rttnning BGP tn 
a closed system and are prevented from advertising their 
networks lu the rest of the Internet via BGP. 

Since there are only 65,536 possible ASN's, it is 
important that you only retjuesl an ASN if you are 
Immediately about to multi-home. No one wall think that you 
are TooP if you have your owm ASN and are not using It. 
Quite the opposite, in fact. 

Once allocated your ASN[10], you are ready to begin 
BGP routing. 
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Building a high technology or Life sciences business? Attend Garage*corn's Bootcamp for Startups 
conference* In two days of intensive, high-energy sessions, you'll get expert advice from major 
players on everything from fundraising and business development to recruiting and marketing. 
Find out how to refine your business model Discover how to position—=and pitch—your startup 
to investors* Network with peers and potential mentors* Learn how to raise funds in today's 
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Getting Started With BGP Routing Commands 

All or the ibllowing examples are based on Cisco's lOS 
ctJmmand set, and show reser\'ed address space for route 
announcements and ASN's. Additionally^ the examples 
shown reflect a hare-bones configuration for simplicity's 
sake. 

It is also assumed that you have already created your 
internal network routes and defined interfaces. 

You should perform your own research before copying 
these examples and deploying them in your networkdlH 

The author would also like to point out that there are 
many different ways to configure BGP, and that best current 
practices are constantly evolving. Study, evaluate and decide 
what configuration parameters, options and methods will be 
best for your network. 

Additionally, you will need to coordinate with your ISP's 
to begin BRP routing. Plan aliead to make sure that they are 
ready to accept your BGP sessions, and that these changes 
are done duing your normal maintenance window in case 
something goes wrong. 

Enter command mode and tell your router what your 
ASN is: 

autonomous-system 64512 

Next, you need to tell the router that you want to enter 
some BGP commands, prevent an arbitrary rcsuter from trying 


to synchronize with ours, and also tell our router what 
networks are local to our ASN: 

router bgp 64512 
no synchronization 

network 191168.0.0 mask 255.255.224.0 
network 191168.145.0 
network 192.168.225.0 
network 10.4.0.0 ma.sk 255.255,0.0 


In the above example, we will be announcing that 
networks 192.168,0/19, 192.168.145/24, 192.168.225/24 and 
10.4/16 belong to ASN 64512. 

Now^ we need to define out BGP neighbors: 

neighbor 172.16.45.3 remoie-as 64828 
neighbor 10.128.47.16 remote-as 65123 

Note that the neighbor addresses are remote port 
address that should be provided by your ISP's, 

Now, we want to tell the router to aggregate our IP address 
blocks for supernetting and to make sure it wall only distribute 
the supernet route and not a more specific network route, 

aggregate-address 192.168.0.0 255.255.224.0 summary-only 
aggregate-address 192.168.(45.0 255.255.255.0 summary-only 
aggregate-address 192.168.225.0 255.255.248.0 summary-only 
aggregate-address 10.4.{).0 255.255.0,0 summary-only 
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Listly, we want to prevent the router fmm auto-,siimmarizing 
BGP-3 routes that are injected into the routing tables: 

no auto-summary 


Noxv esrape out of tTommiind mode and stive your changes. 
Here Ls what it w'ould ltx>k like all printed out togetlien 

aulonoinous-.sysicm 64512 

f 

router bgp 64512 
no synchronization 

network 192.168.0.0 mask 255.255,224.0 

network 192.168.145.0 

network 192.168,225.0 

network 10.4.0.0 mask 255.255.0.0 

neighbor 172.16.45.3 re mote-as 64828 

neighbor 10.128.47,16 remoie-as 6.5123 

aggregate-address 192.168.0,0 255.255.224.0 summary-only 

aggregate-address 192.168.145,0 255.255,255,0 summary-only 

aggregate-address 192468.225.0 255.255.248.0 summary-only 

aggregate-address 10,4,0.0 255,255.0.0 .summary-only 

no auto-sutirmary 


At this prjint, you .should t>e ready to go. Now it is time to 
call your ISP's and have them accept your BGP routing sessions. 
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Once yt]u have a network engineer on the phone, you will need 
to reset your port to force an open message exchange; 

dear ip bgp 172.16 45,3 

Notice that this is die remote port of your ISR You will need 
to do this for each network connection you have w^hen you first 
come online with BGP with that provider. 

You should also confirm with your ISP that they are 
announcing your routes from their BGP sessions to the rest of 
the world (this is what you are paying them for after all!) This 
may require them to update their route filters wliich can take 
some tiiiie, depending upon the ISP. 

Qiecking Your Work 

Now you should check to see that you have everything set 
up and running correctly for traffic flc)wing olu {)f your network 
and to make sure that people can get into your network. 

From your router’s prompt, check to see that you have 
BGP routes to a site outside of your network: 

show ip bgp 17.254.0,91 

This should show an output like this: 

BGP routing lable entry for 17.12K.0.0/9, version 17940452 Pattis: (2 
available, best #2) 

Not Advertised to Any Peer 

64828 702701 10911 714 

172.16.45J (VoTTi 172. ] 6,453 (172.16,45.3) 

Origin IGP, localpref 100, valid, external 65123 1239 10911 714 
it). 128.47.16 from 10.128.47,16(10.128,47,16) 

Origin IGP, Irxialpref 100, valid, external 

This show^s two routes out of your network via different 
neiwrjfks and that the second route is the preferred route due 
to the fact that it has the shortest number of hops thrr^ugh 
other networks to get to the final destination. 

Next, connect to a public route served 12] and perform 
the same command, but with a destination address inside of 
your netw^ork. 

The output should be similar to this: 
show ip bgp 192.168,14.12 

BGP routing table entry Ibr 192.168.0.0/19. version 5055628 Paths: (4 
available, best #3) 

Not advertised to any peer 

64802 64739 64565 64917 65034 64828 64512 172.16.62.94 from 
172.16,62.94 (172.36.62,94) 

Origin IGR localpref 100, valid, externa) 64721 65022 64631 65123 64512 
10,8.3.19 from 10.8,3,19(10.8.3.19) 

Origin IGR localpref 100, valid, external 6294 64828 64512 172.16.12.9 
from 172,16.12.9(172.16.119) 

Origin IGR localpref KX). valid, external 64631 65022 64802 65123 64512 
10.17,224,45 from 10.17,224.45 (10.17.224.45) 

Origin IGR localpref KK). valid, external 


This view shows us ihai there are four routes to our 
network with route number three being the best route. 
Looking at the next to last hop ASN, we see that both of our 
upstream ISP’s are in the ASN path list, so both are 
announcing our routes to the rest of the world. 

If the next to last hop w^as always the same, w^e w'ould 
need to call the ISP that was not shown, and ask them to 
make a route announcemem for us. 

Do be aware that routing announcement changes can 
take up to an hour before routes converge, or are fully 
propagated through the global BGP system. This means that 
iroubieshooting can sometimes be delayed as you wait for 
route convergence. 

What Can Go Wrong 

The careful reader will note in the above examples that 
there is absolutely nothing to prevent you from announcing 
0.0.0,0 or any other netw^ork to your BGP neighbors. When 
you announce routes that you do not own, you 1>lackhole’ 
those routes. 

Rememlier that BGP only propagates routing changes 
and if you announce a network that you do not administer or 
have a route to, the rest of the world will now think that you 
are the best path to that network and start sending you traffic. 
The true network administrator’s traffic begins to drop off to 
zero as the routes converge^ thus a 'Black Hole' network; one 
that does not have a valid route on the Internet. 

These sorts of situations happen in small and large scales 
on the Internet every now and then. In these cases, the false 
routes must be w ithdraw'n by removing tlie incorrect network 
statements and resetting the BGP session. The true 
administrator of the falsely announced network then must 
reset their BGP sessions in order to inject the routes hack 
into the global route lalde. 

This process ohviou.sly needs to happen in a coordinated 
fashion and requires reselling ihe BGP .session. Every time 
you reset a BGP .se.ssion, you 'flap’ a route. This means you 
send a new update message that is passed around the world. 

Many ISP’s do Flap dampening[13] to prevent excessive 
routing table churn» wriiich can slow down route processing. 
Flap dampening works by ignoring BGP update messages 
from a neighbor if the BGP session is reset too many times 
in a given time period. 

Flap dampening prevents minor typos from causing 
excessive route chum. Koute flaps are genemlly caused by 
internal network information leaking into BGP and 
inexperienced BGP network administrators resetting their BGP 
sessions to fix their mi.stakes. Route filtering is wriiere the real 
protection from ignorant mistakes comes into play though. 
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Cisco 3600 Family of Routers 


YoiiVe been residing aboLit BGP and are probably wondering 
about tine type of hard^re that you would need. Aside from a good 
deal of RAM in tlie router, you need to pick a capable router tliat is 
rock solid, and lias the features to make BGP possible. 

For our testing, we went wiili a Cisco 3640 router. We chase 
the 3600 series lxx:ause it liad tlie ability to run cunent versions of 
the Cisco’s 105, as well as have enougli RAM and ports in the box 
to do the job we needed. 

Furtliermore, in our minds, Cisco routers feel like tliat old IV 
conmiercial for Master padlocks. You know, die one where tliey 
shoot a bullet through it, and the lock keeps working? Cisco’s are 
die same way. Iliey just keep going and going :^ind going ... a gocxl 
feature to h:ive in a router. 

Specmcs on tfie 3640 

Tlie Cisco Systems 3600 series is the mulUservLCe solution 
that Cisco says it has designed for "branch offiee.s'^ But, because 
it is flexible, modular, high performance, and cost-effective, it 
may lie gtxid for your main office* :) It all depends on the 
amount of traffic you are flow ing. 

The 3600 Family comes in three main flavors (3620, 3640, and 
the 36f)0) which differ in tlietr expandability and throghput 
capabilities. 71ie 3640 has a lOO-MHz IDT R4700 IdSC proc'essor; 8 
MB Flash, ugradable to 32 MB; I 6 MB DRAM, u[igradable to 128 MB. 

Key Benefits 

What iTuikes the 3640 special is tluit you can do so much with 
it. In one Ixix, you can combine diid-up access, advanced LAN-to- 
LAN routing services, and niuliiservicce integration of voice, video, 
data into a single lx)x. In typical Cist:o Fashion, the design is both 
modular and flexible supporting a wide array of network mcxiules. 
As you w^oLikl expect, everything is highly configurable and .scalable. 

If you are into such tilings, you can tuse the 3640 for sttindards 
ba.sed support for Voice over IP and Voice over Frame Relay. If you 
aren’t alreatly familiar wath Cisctris fully integrated lOS software, it 
comes with extensive security features, and multimedia support with 
robust QoS, and guarinteed inten)|x^rability acrojis Lifl Cisco rt inters. 
Since Cisco routers make up so much of the Internet, fids gives you 
a great deal of interoperability. 

When it comes to management, you’ll lx; able to ust^ a coastjle 
port, Simple Network Managejiient Protocol (SNM!^), orTelnei (or 
remote management and monitoring. 1 laving li simple, cieiai Telnet 
interktce was a !3ig plus for us and made it easy lo acces^s the router 
from anywhere on our network. 

When to Deploy a 3620 or a 3640/3660, and what can 
you do with them 

Of the three, which do you go with? With 2 slots in a Cisco 3620 
with performance o( 20-40 kpps, 4 slots in a Cisco 3640 wifii 
performtince of 50-70 kpps, and 6 slots witliin a 3660 wifii 
perfomiance of 120 kpjDS. It all comes dowm to file nuintxiT of sloLs 
you need and the throughput you want. 

The 3600 series allows you basic hardware iniegration 
including integrated CSU/DSU and analog and digital modems 
to the applications integration of Voice/Fax/Video/Data. The 


Quality of Service (QoS) features of the Cisco lOS and the 
powder to support them at bandwidths in excess of multiple 
Tl/El. Features such as Weighted Fair Queuing (WFQ), IP 
Precedence, Resource Reservation Protocol (RSVP) and 
Committed Access Rate (CAR) provide lioth the traffic shaping 
and prioritization necessary^ for a robust multiservice platform 
that can handle mission critical networking. 

41ie 3600’s can also handle Virtual Prirate Networking (VPN) 
tliroLigh advanced tunneling features ineluding L2F and L2TP, 
standards based IPSEC encryption, lOS Firewifil Feature Set, and 
diverse WAN and dial interfftees to yield a choice great for botli VPN 
entry poioLs and home gatewayi^. 

LAN media support is flexible in that you can support 
Elliernet, Fast Etliernet, and Token Ring as w^ell as high density 
ISDN, async, and analcsg and digital modem support. In a 3640* 
you can have up to 8 PRl, up to 96 ports for supporting 
external modem banks, up to 48 analog (PO'fS) modems, or up 
to 60 digital modems (at 56 kbps speeds). 

How the Cisco 3600 Series Stacks Up 

'Hie Cisco 3600 series (offers support for the most w^ideiy 
used network protocols, including IP, A[>pIeTalk, Novell IPX, 
DECnet, and a wide ninge of routing protocols. For bandwidth 
optimization tlie re are a .series of features including data 
compression and iiiLillipIe tiaffic prioritization lediniques which 
ensure that mission-cTiticai data is accommodated* while features 
such as proroc<>l .spoofing, snapshot routing* bandwidth on 
demand and dial on demand guarantee that the cost of usage- 
based services such as ISDN is minimized. 

There’s enhanced multimedia and virtual LAN (VLAN) 
support: Internal Group Management Protocol* RSVP* Protocol 
Independent Multicast, WFQ, Simple Multica.st Routing Protocol, 
and Inter-Sw'itch Link enable the Cisco 36(K) series to support 
audio and videii service applications as w'cll as virtual LANs. 

For security, there's user authentication and Llie lOS Firewall 
Feature Set allow tmly approved traffic onto the netw'ork. Event 
logging and audit trails, encry ption* and VPN tunneling provide 
increased network security. In addition* TACACS+ and RADIUS 
are also supported. 

OlJR CONaXTSlON 

The only real issues that we faced were that, like many Etliernet 
interfaces from other vendors, autcKseasing of duplex doesn’t 
necessarily work. It’s just safer to Icxk them down manually ... and 
that’s what the experts do. 

If it sounds like wu like the .5640, we do ... a lot... and higlily 
recommend them f<:r Ixutli file heart of your netw^ork and file 
satellite office communications tliat you may want to fiidlitate, 

'file nice filing aixjut Cisco’s line is fiiat il’ this is too much or 
texj little of a lx3X for your needs* tliere are additional models above 
::ind below^ it .., and lliey all wc^rk in a consistent wuy. 

You can find more information out about Cisco and their 
products at; Cisco Systems Inc.* 170 West Tasman Drive, San 
Jo.se* CA 95134* http://www.dsco.com* 8(X)-553-NETS (6387)* 408- 
526-1000, Fax: 408-526-4100. Ei 
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Protecting Your Networks 
Route filtering is more granular because you can pick and 
choose which networks you want to accept into your BGP 
routing table. Route filtering for your network should reflect 
your netw'ork's policy of what routes you want to accept and 
reject, and to protect you from other people’s mistakes. 

A solid route filtering policy[l4] will prevent die acceptance 
of nonsensical route.s that could cause all soit.s of liavoc if' you 
accepted them and then passed them on to your neighbors. 

Examples of routes you want to avoid are the default route 
of 0.0.0.0, any RFC 1918[151 addre.ss space, loopback, etc. 

Do bear in mind that if you place more than one BGP 
neiwxirk engineer in a room, you can instantly stan a debate that 
could rise to fisticuffs by casually .suggesting what a 'perfect’ 
BGP route filter policy is. Everyone’s network is different, and as 
such, your route filtering policy should reflect your goals. 

Public route servers,! 16] wliere network engineers store 
network route infomiation, is one source of information that can be 
used in building route policies. Tliese LRR’s (Internet Routing 
Registries) provide an autoimted way to build your route filtering 
policies by pulling down netw^ork route information and 
programmatically building route filters Ixused on tlie data retrieved. 

Conclusion 

Multihomlng your network and running BGP is a boon to 
network uptime as it provides multiple rtiutes in and out of your 
network for tniffic to tlcw on. Tlie dowaiside is that the 
requirements to do BGP routing am be hard to attain without 
demonstrated need, sufficient capital and experienced staff, 

Tf you feel that you need the l>enefits of BGP, but feel tliat 
migrating to BGP louting is beyond your organization's ability, 
you should investigate other methods of network redundancy 
which are easier to implement. As part of those methods, be sure 
to utilize ISP’s that are using BGP and are willing to assist you 
with implementing your redundant configurations. 

[1] http://vwvwireesoft.org/CIE/RFC/Orig/rfc827.txt 

[2] http://wvw\/.ds.oh io-state.edu/htbrn/rfc/rfc1771. html 

[3] http://www.cisco.com/warp/publid459/25.htnil 
[41http://www.arin.net/regserv.html 
[51http://www.arin.net/regserv/tnitial-isp.ht[Til 
[6]http://www.arin.nel7regsew/asriguide.htm 
E7]http://www.ann.net 

[8] hnp://wvwy.riperiet 

[9] http://wvw.apinc.net 

no) ftp://rs.arin,net/netinfo/asn.txt 

[11] http://www,cisco,com/univercd/cc/td/ctoc/product/software/ 
ios120/l2cga/np1_c/kprt1/1cbgp,htrTi 

[12] http://vww,rTierit,edu/--ipma/tools/lookingglass.html 

[13| http://www.iTerit.edu/ir)ternet/docurnents/rfc/ifc2439.txt 
1141 http://vwwv.merit.edu/ipma/docs/help.html 

[15] http://vwwv.merit.edu/internet/documents/rfc/rfc1918.txt 

[16] http://vwwv.radb.net/ 
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MAC SECURITY 


By Jesse Coii>eil, Montreal Quebec 


Mac OS X Security 


Securing a Mac OS X workstation 
for stand-alone or home use out of 
the box 


Note: JVIac OS X is currently in Public Beta. The 
final version may invalidate any or all of diis papen 
That’s just a chance %ve take when we write how-tos 
about beta operating systems 

In the world of operating systems^ the Macintosh 
platfonn has traditionally been everybody else's secure 
neighbour. Not many vtrii nr cracks affected die Mac 
(unless we counted cross-platform Word macros), and 
we were generally spared the heaps of abuse that were 
laid onto our Windows-using l7rethren. Whelher this 
has been due to the brotherly Mac community or the 
simple fact that there aren't enough Mac OS compyters 
out there to make it worthwhile is up for debate. The 
truth will become clear when we all trash our old Macs 
and buy brand-new' Cubes to run Apple’s swank new 
OS. Why is that? Because Mac OS X is nothing more 
than a shiny interface on top of a tw^eaked BSD core., 
and BS1> is very much si tigging it out at the centre of 
the cracks and exploits blattleground. With that in 
mind, this article will discuss how^ to secure the default 
installation for a workstation or for home use. 

BSD 

Unix-cowboys have it all over us Mac users. They 
trade in the ease-of-use and smt)(>rh operation to w hich 
we are accustomed on the Mac side for raw, unlimited 
power over their machines. The easy Mac or Windows 
click-to-install approach is shunned in favour of the 
ability to tweak the code of an app that didn’t install 
properly; cutting, thwacking, and generally forcing the 
code until the app clicks smoothly into place. Further, 


whereas we tend to troubleshoot by twiddling the 
knobs and banging the pipes, Unix-gurus crawl under 
the sink to pull the works apart. They know their 
machines belter than we know our mothers. 

Now, aU that is ahe^ut to change— at least for those 
of us who actually w^ant to dig about under the hood 
and still enjoy the Mac OS experience. 

With the change to Mac OS X, Apple reduces the 
number of major-player non-|lnix OSes by one, while 
simaulmneously giving the Irnix world something it has 
been trying to develop w ith imperfect solutions like KDE 
and Gnome: a distro with a polislied and usable GUI. 

What the HSl> core tfetchingly called 'DarwinO 
gives f>ack to the Mac is a rock-solid OS with all the 
buzz-technologies incorporated: muUi-this, protected- 
ihal, and the new-to-Mac concept of an application 
crashing without taking down the OS. Unfortunately, 
what else we get is a security headache. Suddenly, all 
those Unix-savvy hacks and virii are mac-savvy too. 
Added to that (and I feel safe in going out on this 
particular limb), the country-bumpkin image that the 
Mac OS has enjoyed in hacker circles is about to be 
replaced by a perception of the OS as the sexy new^ 
Unix. Eager crackers will w^ant to try out all the exploits 
and probe the nooks and crannies. 

The Swiss-Cheese OS 

Once they’ve been properly set up, the BSDs are 
generally pretty secure. They are developed by 
security-conscious communities and tend to be 
deployed in sensitive areas like networking and 
databasing. The Calgary-based OpenBSD is regarded 
as the most secure BSD distribution, incorporating 
many crypto and security features that would be non- 
exportable had it been an American distro subject to US 
export laws. Obviously, Apple could not have based 
Mac OS X in Open BSD and still sold the OS outside 


Jesse Corbcil is the Direaor of Dcxiimentation at SecureOps, a network security consulting firm in Montreal, Canada, He has wriUen For 
beoscentral.com and several other information sites, and is involved in the Mamthon Open Source project. 
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the US, but the more freely-exporiable BSDs are still 
very secure, and the choice to base Mac OS X on the 
platform is still a solid one. 

OpenBSD aside, any distro must be properly 
hardened to close up some of the dozens of holes left 
open by a default instalJaiion. This is where Darwin 
shows its BSD roots, and where a certain familiarity 
with Unix system hardening comes in. On a typical 
BSD system, one of the things an admin would do to 
secure the system is to edit the inetd.conf file to 
disable unneeded services. Mac OS X comes with the 
inetd.conf file already set up in a pretty secure 
configuration, but that doesn't mean that the OS is 
completely tight. There are other security holes in the 
default setup (such as services not covered by 
inetd.conf) that must be addressed before deploying 
the OS in a secured environment. When configLiring 
services, the general rule of thumb is If youTe not 
using it, turn it off 

'Ihere are some cool gewgaws in Mac OS X, 
though their default configurations can be pretty 
insecure. Running dmesg, for instance, reveals that 
there is an IP packet filter initialised l'>ut that it's wide 
open; The NFS daemon is active hy default, which 
opens up a security hole, as does the Port map 
daemon. There's an NTP daemon enabled, which 
opens a very slight security risk: though one wouldn't 
generally try to compromise the system through NTP, it 
is theoretically possible to muck about with it to make 
time-sensitive apps do one's bidding. But by far the 
coolest feature of the OS in terms of un-fubar-abiliry i.s 
the separation of admin accounts from the central, alb 
pow^erful root user. A.s part of the OS installation, 1 was 
asked to create an administrator account for myself. 1 
.set die system up as ''jcorbeil," which is the account 1 
generally use. From there 1 can administer just ahout 
anything on the machine — so kmg as the function is 
GUI accessible. How'ever, if 1 try to enter rm -rf * in a 
Terminal window% the system wall tell me to stuff 
myself Why is this? It's due to Apple's approach to 
Mac CSX's design. Apple has made it as difficult as 
possible to hose your system by limiting GUI access to 
most of the really dangerous functions. Thai's a smart 
move on Apple's pari, as it effectively slops non-gurus 
from inadvertently committing atrocities. 

Another safety feature w^as revealed when 1 
checked out the Netlnfo application, which is where 
all system and user information is centralised. I 
discovered (and verified via a quick etc/passwd check) 
that even though my account is an administrator 
account, the system still pledges its allegiance to a 
separate root account that was automatically generated 
during installation. In ocher words, “jeorbeir' may be 


the system admin, but he doesn't have the same set of 
priviledges as the bonafide root user To do something 
that only the root can (like erase the works), 1 have to 
su to root in Terminal, then do my damage. It’s not 
hard, as the root account shares jcorbeil’s password by 
default, but there's a certain level of know-how 
involved in getting to the 'destroy-the-OS' point that is 
beyond the ken of most new users coming from a 
classic Mac OS background. 

Openings and Closings 

To get a bit of an aperyu of what ports are open on 
your system, open a Terminal window and enter 
netstat -an (Figure 1). This will display your machine's 
ports and whether they are listening, established, or 
closed. If you want to see the ports' names, use the 
netstat -a command. It's a safe bet that you'll find ports 
you don't recogni.se. t hat's normaf but for for tho.se 
who want to know all about ports, 
http://www.dosheIp,com/trojanports.htm ha.s some resources 
for the inquisutive firewall admin. 



Figure L What comes itp when you type neisiai -an 

Chances are, you’ll find two local addresses near 
the bottom of the list, called *.111 and *.514. These are 
our first two security issues. *.111 is portmap, which is 
a daemon for making RPC calls. It is aLso lousy for 
security, and is best turned off *.514 is the syslog 
daemon, which listens on LI DP and receives log 
broadcasts from other servers. Sounds pretty innocuous, 
right? Well, UDP is not a two-way protocol, so there's 
no way for syslog to verify w'hether or not the sender 
of a given datum is who he .says he is, which opens up 
the potential for a denial of service attack. Nasty stuff. 
Tighten *.514 up l:>y using IFF to stop connections other 
than 127,0.0.1 (more on this later). 
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After that, nan a search for any files that are either 
world-writeable or owned by the “nobody” user or 
group. Every one of these opens up a little security 
hole, and should therefore be viewed with great 
circumspection. You might need a couple of them, you 
miglit not. Look about and clean up what you can by 
tightening up the access conirol to world-writeable 
files or files with 'nobody’ tawncrship. 

IPFilter; Built-in Security 

IP Filter is a firewall that gets installed with the 
kernel, and is where some of the power of a BSD- 
based OS comes to the fore. IPFilter alone warrants a 
book or tw^o, but there are some basics that everyone 
can use as a springboard to using IPF fairly quickly. 

IPF works by processing a rules file. The rules file 
is a text file of conditions and actions for IPF to take 
when those conditions come to pass, for example 
blocking packets, letting packets through, and logging 
them. Set up IPF’s rules file for l>locking, passing, and 
lagging based upon the criteria you want to employ. 
For example, say you don’t want TCP packets coming 
in. You would edit the ipTrules file by entering the 
following line of text: 

block in on edO proto tcp from any to any 

If you wanted the above to block only one port 
(say ^,514), you would change the text to read: 

bkock in on edO proto Lcp from any to any port = 514. 

Fiddle with the file, blocking and unblocking ports 
until you have a tight system from w-hich you can still 
run the transactions you need. It is generally a good 
idea to start off your rules file with a command to 
block all ports. That way, any port that doesn’t have a 
rule expressly attributed to it is covered by the first 
rule, and is l>locked, 

IFF is quite powerful, and it's a good idea to become 
well-acquainted with it. More in-depth information can 
be found at http://coombs.anu.edu.au/ipfilter. 

SSH AND Kerberos 

Two things that 1 haven’t touched on in this article 
are SSH and Kerberos, That has been done on 
purpose, as there is very little to be dcme with either 
of them for a home or standalone system set-up. SSH 
comes as part of the standard instaliation and is an 
extremely effective tool for keeping your system tight. 
For our purpo.ses, you won’t need to change the 
configuration. Just be serene in the knowledge that it's 
running and it has your safety in mind. Accordingly, 
you don’t need to run services like rsh, telnet, rlogin, 


or ftp. They represent unneeded security risks, so 
unless you expressly need one of them for something, 
shut them down. 

Kerberos uses a client/server setup, and you would 
only worry about Kerberos if you were on a network 
that uses the protocol. Since w^eTe securing a home 
machine, we'll leave Kerberos alone. 

Take it to the Bone 

These solutions are not the be-all, end-all secret to 
how to secure your home system from a brilliant 
hacker, but they do form a soHd foundation from 
wdiich you can do further research into the methods 
and tools available to secure your computer. If you 
want to read further, check out the lE^ FilterFAQ at 
http://coonnbs.anu.edu.au/ipfilter/ipfilfaq.html, or read 
O'Reilly’s Practical UNIX & Internet Security by 
Garfinkel and Spafford. 

Whether or not you decide to delve into the deep, 
dark depths of computer security, a basic knowledge 
will still help you understand the basics. Basic 
knowledge will at least let you understand the theory 
behind a security breach chat might nail your machine, 
and understanding will hand you the keys you need to 
get the problem fixed. Computer security doesn’t have 
to be sc^jny, indeed, it can even sometimes he fun. 
Getting caught unawares by a cracker, on the other 
hand, can cause you immeasurable pain. Kl 
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